@feedhog/js 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,338 @@
+/**
+ * Feedhog SDK Types
+ * These types mirror the API response types from the Feedhog server.
+ */
+type FeedbackType = "bug" | "idea" | "question" | "other";
+type FeedbackStatus = "new" | "under-review" | "planned" | "in-progress" | "completed" | "closed";
+type SortBy = "newest" | "oldest" | "votes" | "comments";
+/**
+ * SDK Configuration
+ */
+interface FeedhogConfig {
+    /** Public API key (starts with fhpk_) */
+    apiKey: string;
+    /** Base URL for the API (defaults to https://feedhog.com) */
+    baseUrl?: string;
+}
+/**
+ * User identification data
+ */
+interface UserIdentity {
+    /** Your system's unique user ID */
+    externalId: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** URL to user's avatar image */
+    avatarUrl?: string;
+    /** Additional metadata to associate with the user */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Feedback submission input
+ */
+interface SubmitFeedbackInput {
+    /** Feedback title (required) */
+    title: string;
+    /** Detailed description */
+    description?: string;
+    /** Type of feedback */
+    type?: FeedbackType;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for listing feedback
+ */
+interface ListFeedbackOptions {
+    /** Filter by status(es) */
+    status?: FeedbackStatus | FeedbackStatus[];
+    /** Filter by type(s) */
+    type?: FeedbackType | FeedbackType[];
+    /** Search query */
+    search?: string;
+    /** Sort order */
+    sortBy?: SortBy;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page (max 100) */
+    limit?: number;
+}
+/**
+ * Feedback author info (public)
+ */
+interface FeedbackAuthor {
+    name: string | null;
+    avatarUrl: string | null;
+}
+/**
+ * Comment author info (public)
+ */
+interface CommentAuthor {
+    name: string | null;
+    avatarUrl?: string | null;
+    isTeam?: boolean;
+}
+/**
+ * Public comment on feedback
+ */
+interface FeedbackComment {
+    id: string;
+    content: string;
+    createdAt: string;
+    author: CommentAuthor | null;
+}
+/**
+ * Feedback item from list endpoint
+ */
+interface FeedbackListItem {
+    id: string;
+    title: string;
+    description: string | null;
+    type: FeedbackType;
+    status: FeedbackStatus;
+    voteCount: number;
+    commentCount: number;
+    createdAt: string;
+    endUser: FeedbackAuthor | null;
+}
+/**
+ * Feedback item with full details
+ */
+interface FeedbackDetail extends FeedbackListItem {
+    userHasVoted: boolean;
+    comments: FeedbackComment[];
+}
+/**
+ * Paginated response
+ */
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * Vote result
+ */
+interface VoteResult {
+    voted: boolean;
+    voteCount: number;
+}
+/**
+ * Identified user response
+ */
+interface IdentifiedUser {
+    id: string;
+    email: string | null;
+    name: string | null;
+    avatarUrl: string | null;
+    createdAt: string;
+}
+/**
+ * Internal: Current user state
+ */
+interface CurrentUser extends UserIdentity {
+    identified: boolean;
+}
+
+/**
+ * Feedhog API Client
+ * Handles all HTTP communication with the Feedhog API.
+ */
+
+/**
+ * API Error with status code and optional validation details
+ */
+declare class FeedhogApiError extends Error {
+    readonly status: number;
+    readonly details?: {
+        formErrors: string[];
+        fieldErrors: Record<string, string[]>;
+    } | undefined;
+    constructor(message: string, status: number, details?: {
+        formErrors: string[];
+        fieldErrors: Record<string, string[]>;
+    } | undefined);
+}
+
+/**
+ * Simple event emitter for SDK events
+ */
+declare class EventEmitter<Events extends {
+    [key: string]: unknown;
+}> {
+    private listeners;
+    on<K extends keyof Events>(event: K, callback: (data: Events[K]) => void): () => void;
+    emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    off<K extends keyof Events>(event: K, callback: (data: Events[K]) => void): void;
+}
+
+/**
+ * Feedhog JavaScript SDK
+ *
+ * Collect user feedback from any website or application.
+ *
+ * @example
+ * ```typescript
+ * import Feedhog from '@feedhog/js';
+ *
+ * const feedhog = new Feedhog({ apiKey: 'fhpk_xxx' });
+ *
+ * // Identify the current user (optional but recommended)
+ * feedhog.identify({
+ *   externalId: 'user-123',
+ *   email: 'user@example.com',
+ *   name: 'John Doe'
+ * });
+ *
+ * // Submit feedback
+ * await feedhog.submit({
+ *   title: 'Add dark mode',
+ *   description: 'Would love a dark theme option',
+ *   type: 'idea'
+ * });
+ * ```
+ */
+
+interface FeedhogEvents {
+    [key: string]: unknown;
+    identify: IdentifiedUser;
+    submit: FeedbackListItem;
+    vote: {
+        feedbackId: string;
+        result: VoteResult;
+    };
+    error: Error;
+    reset: void;
+}
+/**
+ * Feedhog SDK main class
+ */
+declare class Feedhog extends EventEmitter<FeedhogEvents> {
+    private readonly client;
+    private currentUser;
+    constructor(config: FeedhogConfig);
+    /**
+     * Get the currently identified user
+     */
+    get user(): CurrentUser | null;
+    /**
+     * Identify the current user
+     *
+     * This associates feedback and votes with a specific user in your system.
+     * User data is persisted in localStorage for subsequent sessions.
+     *
+     * @param user - User identity data
+     * @returns Promise resolving to the identified user
+     *
+     * @example
+     * ```typescript
+     * await feedhog.identify({
+     *   externalId: 'user-123',
+     *   email: 'user@example.com',
+     *   name: 'John Doe',
+     *   metadata: { plan: 'pro' }
+     * });
+     * ```
+     */
+    identify(user: UserIdentity): Promise<IdentifiedUser>;
+    /**
+     * Submit new feedback
+     *
+     * If a user has been identified, the feedback will be associated with them.
+     *
+     * @param input - Feedback data
+     * @returns Promise resolving to the created feedback item
+     *
+     * @example
+     * ```typescript
+     * const feedback = await feedhog.submit({
+     *   title: 'Add dark mode',
+     *   description: 'Would love a dark theme option',
+     *   type: 'idea'
+     * });
+     * console.log('Feedback submitted:', feedback.id);
+     * ```
+     */
+    submit(input: SubmitFeedbackInput): Promise<FeedbackListItem>;
+    /**
+     * List feedback items
+     *
+     * Returns a paginated list of feedback for the project.
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated feedback list
+     *
+     * @example
+     * ```typescript
+     * // Get all ideas in "planned" status
+     * const { items, total } = await feedhog.list({
+     *   status: ['planned', 'in-progress'],
+     *   type: 'idea',
+     *   sortBy: 'votes',
+     *   limit: 10
+     * });
+     * ```
+     */
+    list(options?: ListFeedbackOptions): Promise<PaginatedResponse<FeedbackListItem>>;
+    /**
+     * Get a single feedback item with full details
+     *
+     * @param feedbackId - ID of the feedback item
+     * @returns Promise resolving to feedback details including comments
+     *
+     * @example
+     * ```typescript
+     * const feedback = await feedhog.get('abc123');
+     * console.log('Comments:', feedback.comments.length);
+     * console.log('Has voted:', feedback.userHasVoted);
+     * ```
+     */
+    get(feedbackId: string): Promise<FeedbackDetail>;
+    /**
+     * Toggle vote on a feedback item
+     *
+     * If the user has already voted, this will remove their vote.
+     * If they haven't voted, it will add their vote.
+     *
+     * @param feedbackId - ID of the feedback item to vote on
+     * @returns Promise resolving to vote result
+     *
+     * @example
+     * ```typescript
+     * const { voted, voteCount } = await feedhog.vote('abc123');
+     * console.log(voted ? 'Vote added' : 'Vote removed');
+     * console.log('Total votes:', voteCount);
+     * ```
+     */
+    vote(feedbackId: string): Promise<VoteResult>;
+    /**
+     * Check if the current user has voted on a feedback item
+     *
+     * @param feedbackId - ID of the feedback item
+     * @returns Promise resolving to vote status
+     *
+     * @example
+     * ```typescript
+     * const { voted, voteCount } = await feedhog.hasVoted('abc123');
+     * ```
+     */
+    hasVoted(feedbackId: string): Promise<VoteResult>;
+    /**
+     * Reset the SDK state
+     *
+     * Clears the current user and removes stored data.
+     * Use this when a user logs out.
+     *
+     * @example
+     * ```typescript
+     * feedhog.reset();
+     * ```
+     */
+    reset(): void;
+}
+
+export { type CurrentUser, type FeedbackDetail, type FeedbackListItem, type FeedbackStatus, type FeedbackType, Feedhog, FeedhogApiError, type FeedhogConfig, type IdentifiedUser, type ListFeedbackOptions, type PaginatedResponse, type SortBy, type SubmitFeedbackInput, type UserIdentity, type VoteResult, Feedhog as default };

package/dist/index.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Feedhog SDK Types
+ * These types mirror the API response types from the Feedhog server.
+ */
+type FeedbackType = "bug" | "idea" | "question" | "other";
+type FeedbackStatus = "new" | "under-review" | "planned" | "in-progress" | "completed" | "closed";
+type SortBy = "newest" | "oldest" | "votes" | "comments";
+/**
+ * SDK Configuration
+ */
+interface FeedhogConfig {
+    /** Public API key (starts with fhpk_) */
+    apiKey: string;
+    /** Base URL for the API (defaults to https://feedhog.com) */
+    baseUrl?: string;
+}
+/**
+ * User identification data
+ */
+interface UserIdentity {
+    /** Your system's unique user ID */
+    externalId: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** URL to user's avatar image */
+    avatarUrl?: string;
+    /** Additional metadata to associate with the user */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Feedback submission input
+ */
+interface SubmitFeedbackInput {
+    /** Feedback title (required) */
+    title: string;
+    /** Detailed description */
+    description?: string;
+    /** Type of feedback */
+    type?: FeedbackType;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for listing feedback
+ */
+interface ListFeedbackOptions {
+    /** Filter by status(es) */
+    status?: FeedbackStatus | FeedbackStatus[];
+    /** Filter by type(s) */
+    type?: FeedbackType | FeedbackType[];
+    /** Search query */
+    search?: string;
+    /** Sort order */
+    sortBy?: SortBy;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page (max 100) */
+    limit?: number;
+}
+/**
+ * Feedback author info (public)
+ */
+interface FeedbackAuthor {
+    name: string | null;
+    avatarUrl: string | null;
+}
+/**
+ * Comment author info (public)
+ */
+interface CommentAuthor {
+    name: string | null;
+    avatarUrl?: string | null;
+    isTeam?: boolean;
+}
+/**
+ * Public comment on feedback
+ */
+interface FeedbackComment {
+    id: string;
+    content: string;
+    createdAt: string;
+    author: CommentAuthor | null;
+}
+/**
+ * Feedback item from list endpoint
+ */
+interface FeedbackListItem {
+    id: string;
+    title: string;
+    description: string | null;
+    type: FeedbackType;
+    status: FeedbackStatus;
+    voteCount: number;
+    commentCount: number;
+    createdAt: string;
+    endUser: FeedbackAuthor | null;
+}
+/**
+ * Feedback item with full details
+ */
+interface FeedbackDetail extends FeedbackListItem {
+    userHasVoted: boolean;
+    comments: FeedbackComment[];
+}
+/**
+ * Paginated response
+ */
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * Vote result
+ */
+interface VoteResult {
+    voted: boolean;
+    voteCount: number;
+}
+/**
+ * Identified user response
+ */
+interface IdentifiedUser {
+    id: string;
+    email: string | null;
+    name: string | null;
+    avatarUrl: string | null;
+    createdAt: string;
+}
+/**
+ * Internal: Current user state
+ */
+interface CurrentUser extends UserIdentity {
+    identified: boolean;
+}
+
+/**
+ * Feedhog API Client
+ * Handles all HTTP communication with the Feedhog API.
+ */
+
+/**
+ * API Error with status code and optional validation details
+ */
+declare class FeedhogApiError extends Error {
+    readonly status: number;
+    readonly details?: {
+        formErrors: string[];
+        fieldErrors: Record<string, string[]>;
+    } | undefined;
+    constructor(message: string, status: number, details?: {
+        formErrors: string[];
+        fieldErrors: Record<string, string[]>;
+    } | undefined);
+}
+
+/**
+ * Simple event emitter for SDK events
+ */
+declare class EventEmitter<Events extends {
+    [key: string]: unknown;
+}> {
+    private listeners;
+    on<K extends keyof Events>(event: K, callback: (data: Events[K]) => void): () => void;
+    emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    off<K extends keyof Events>(event: K, callback: (data: Events[K]) => void): void;
+}
+
+/**
+ * Feedhog JavaScript SDK
+ *
+ * Collect user feedback from any website or application.
+ *
+ * @example
+ * ```typescript
+ * import Feedhog from '@feedhog/js';
+ *
+ * const feedhog = new Feedhog({ apiKey: 'fhpk_xxx' });
+ *
+ * // Identify the current user (optional but recommended)
+ * feedhog.identify({
+ *   externalId: 'user-123',
+ *   email: 'user@example.com',
+ *   name: 'John Doe'
+ * });
+ *
+ * // Submit feedback
+ * await feedhog.submit({
+ *   title: 'Add dark mode',
+ *   description: 'Would love a dark theme option',
+ *   type: 'idea'
+ * });
+ * ```
+ */
+
+interface FeedhogEvents {
+    [key: string]: unknown;
+    identify: IdentifiedUser;
+    submit: FeedbackListItem;
+    vote: {
+        feedbackId: string;
+        result: VoteResult;
+    };
+    error: Error;
+    reset: void;
+}
+/**
+ * Feedhog SDK main class
+ */
+declare class Feedhog extends EventEmitter<FeedhogEvents> {
+    private readonly client;
+    private currentUser;
+    constructor(config: FeedhogConfig);
+    /**
+     * Get the currently identified user
+     */
+    get user(): CurrentUser | null;
+    /**
+     * Identify the current user
+     *
+     * This associates feedback and votes with a specific user in your system.
+     * User data is persisted in localStorage for subsequent sessions.
+     *
+     * @param user - User identity data
+     * @returns Promise resolving to the identified user
+     *
+     * @example
+     * ```typescript
+     * await feedhog.identify({
+     *   externalId: 'user-123',
+     *   email: 'user@example.com',
+     *   name: 'John Doe',
+     *   metadata: { plan: 'pro' }
+     * });
+     * ```
+     */
+    identify(user: UserIdentity): Promise<IdentifiedUser>;
+    /**
+     * Submit new feedback
+     *
+     * If a user has been identified, the feedback will be associated with them.
+     *
+     * @param input - Feedback data
+     * @returns Promise resolving to the created feedback item
+     *
+     * @example
+     * ```typescript
+     * const feedback = await feedhog.submit({
+     *   title: 'Add dark mode',
+     *   description: 'Would love a dark theme option',
+     *   type: 'idea'
+     * });
+     * console.log('Feedback submitted:', feedback.id);
+     * ```
+     */
+    submit(input: SubmitFeedbackInput): Promise<FeedbackListItem>;
+    /**
+     * List feedback items
+     *
+     * Returns a paginated list of feedback for the project.
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated feedback list
+     *
+     * @example
+     * ```typescript
+     * // Get all ideas in "planned" status
+     * const { items, total } = await feedhog.list({
+     *   status: ['planned', 'in-progress'],
+     *   type: 'idea',
+     *   sortBy: 'votes',
+     *   limit: 10
+     * });
+     * ```
+     */
+    list(options?: ListFeedbackOptions): Promise<PaginatedResponse<FeedbackListItem>>;
+    /**
+     * Get a single feedback item with full details
+     *
+     * @param feedbackId - ID of the feedback item
+     * @returns Promise resolving to feedback details including comments
+     *
+     * @example
+     * ```typescript
+     * const feedback = await feedhog.get('abc123');
+     * console.log('Comments:', feedback.comments.length);
+     * console.log('Has voted:', feedback.userHasVoted);
+     * ```
+     */
+    get(feedbackId: string): Promise<FeedbackDetail>;
+    /**
+     * Toggle vote on a feedback item
+     *
+     * If the user has already voted, this will remove their vote.
+     * If they haven't voted, it will add their vote.
+     *
+     * @param feedbackId - ID of the feedback item to vote on
+     * @returns Promise resolving to vote result
+     *
+     * @example
+     * ```typescript
+     * const { voted, voteCount } = await feedhog.vote('abc123');
+     * console.log(voted ? 'Vote added' : 'Vote removed');
+     * console.log('Total votes:', voteCount);
+     * ```
+     */
+    vote(feedbackId: string): Promise<VoteResult>;
+    /**
+     * Check if the current user has voted on a feedback item
+     *
+     * @param feedbackId - ID of the feedback item
+     * @returns Promise resolving to vote status
+     *
+     * @example
+     * ```typescript
+     * const { voted, voteCount } = await feedhog.hasVoted('abc123');
+     * ```
+     */
+    hasVoted(feedbackId: string): Promise<VoteResult>;
+    /**
+     * Reset the SDK state
+     *
+     * Clears the current user and removes stored data.
+     * Use this when a user logs out.
+     *
+     * @example
+     * ```typescript
+     * feedhog.reset();
+     * ```
+     */
+    reset(): void;
+}
+
+export { type CurrentUser, type FeedbackDetail, type FeedbackListItem, type FeedbackStatus, type FeedbackType, Feedhog, FeedhogApiError, type FeedhogConfig, type IdentifiedUser, type ListFeedbackOptions, type PaginatedResponse, type SortBy, type SubmitFeedbackInput, type UserIdentity, type VoteResult, Feedhog as default };