@census-ai/census-sdk 0.1.0 → 0.2.1

package/dist/react/index.d.cts

@@ -188,6 +188,21 @@ interface Request {
     rating: number | null;
     helpful: boolean | null;
     metadata: Record<string, unknown>;
+    vote_count: number;
+    user_has_voted: boolean;
+    is_own: boolean;
+}
+/**
+ * Feedback visibility setting
+ */
+type FeedbackVisibility = 'own' | 'organization' | 'all';
+/**
+ * Project settings for requests
+ */
+interface RequestsSettings {
+    feedbackVisibility: FeedbackVisibility;
+    allowVoting: boolean;
+    allowRequestCreation: boolean;
 }
 /**
  * Options for fetching requests
@@ -223,6 +238,7 @@ interface RequestsResponse {
         offset: number;
         hasMore: boolean;
     };
+    settings: RequestsSettings;
 }
 /**
  * Position for floating UI elements
@@ -389,6 +405,99 @@ interface CensusProviderProps {
      */
     children: React.ReactNode;
 }
+interface GuideStep {
+    id: string;
+    sort_order: number;
+    selector_strategy: SelectorStrategy;
+    title: string | null;
+    content: string | null;
+    tooltip_position: TooltipPosition;
+    actions: GuideAction[];
+    wait_for: WaitForType;
+    wait_config: Record<string, unknown>;
+}
+interface SelectorStrategy {
+    css?: string;
+    xpath?: string;
+    text?: string;
+    testId?: string;
+}
+type TooltipPosition = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+type WaitForType = 'click' | 'next_button' | 'delay' | 'custom';
+interface GuideAction {
+    type: 'click' | 'input' | 'navigate' | 'custom';
+    config: Record<string, unknown>;
+}
+interface Guide {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    trigger_type: GuideTriggerType;
+    trigger_config: TriggerConfig;
+    theme: GuideTheme;
+    allow_skip: boolean;
+    show_progress: boolean;
+    guide_steps: GuideStep[];
+}
+type GuideTriggerType = 'manual' | 'url_match' | 'first_visit' | 'event';
+interface TriggerConfig {
+    url_pattern?: string;
+    event_name?: string;
+    delay_ms?: number;
+}
+interface GuideTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+}
+interface GuidesResponse {
+    guides: Guide[];
+    completedGuides: string[];
+}
+type GuideEventType = 'started' | 'step_viewed' | 'step_completed' | 'completed' | 'skipped' | 'dismissed';
+/**
+ * A feature within a feature group
+ */
+interface Feature {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: string;
+    article_count: number;
+}
+/**
+ * A group of related features
+ */
+interface FeatureGroup {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    color: string | null;
+    features: Feature[];
+    feature_count: number;
+    article_count: number;
+}
+/**
+ * Response from feature groups endpoint
+ */
+interface FeatureGroupsResponse {
+    feature_groups: FeatureGroup[];
+}
+interface GuideAnalyticsEvent {
+    guideId: string;
+    eventType: GuideEventType;
+    stepId?: string;
+    stepIndex?: number;
+    pageUrl?: string;
+    sessionId: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
 
 /**
  * Census SDK Client
@@ -500,6 +609,21 @@ declare class CensusClient {
      * ```
      */
     getArticle(slugOrId: string): Promise<Article | null>;
+    /**
+     * Fetch feature groups with their features and article counts.
+     * Used for navigation in the knowledge base.
+     *
+     * @returns Feature groups with nested features
+     *
+     * @example
+     * ```typescript
+     * const { feature_groups } = await census.getFeatureGroups();
+     * feature_groups.forEach(group => {
+     *   console.log(group.name, group.features.length);
+     * });
+     * ```
+     */
+    getFeatureGroups(): Promise<FeatureGroupsResponse>;
     /**
      * Fetch the current user's submitted requests (feedback, bugs, feature requests).
      * Requires a user to be identified first.
@@ -520,6 +644,29 @@ declare class CensusClient {
      * ```
      */
     getRequests(options?: RequestsOptions): Promise<RequestsResponse>;
+    /**
+     * Vote on a feedback request (toggle).
+     * If the user has already voted, removes the vote.
+     * If the user hasn't voted, adds a vote.
+     *
+     * @param feedbackId - ID of the feedback to vote on
+     * @returns Vote result with action taken and new vote count
+     *
+     * @example
+     * ```typescript
+     * // Vote on a feedback request
+     * const result = await census.vote('feedback-id-123');
+     * console.log(result.action); // 'added' or 'removed'
+     * console.log(result.vote_count); // 5
+     * console.log(result.user_has_voted); // true
+     * ```
+     */
+    vote(feedbackId: string): Promise<{
+        success: boolean;
+        action: 'added' | 'removed';
+        vote_count: number;
+        user_has_voted: boolean;
+    }>;
     /**
      * Track a custom analytics event.
      *
@@ -553,6 +700,64 @@ declare class CensusClient {
      * ```
      */
     trackBatch(options: BatchEventsOptions): Promise<void>;
+    /**
+     * Fetch available guides for the current user.
+     * Returns guides that match the user's context and haven't been completed.
+     *
+     * @returns Guides and list of completed guide IDs
+     *
+     * @example
+     * ```typescript
+     * const { guides, completedGuides } = await census.getGuides();
+     * guides.forEach(guide => console.log(guide.name));
+     * ```
+     */
+    getGuides(): Promise<GuidesResponse>;
+    /**
+     * Fetch a single guide by slug or ID.
+     *
+     * @param slugOrId - Guide slug or ID
+     * @returns Guide or null if not found
+     *
+     * @example
+     * ```typescript
+     * const guide = await census.getGuide('onboarding-tour');
+     * if (guide) {
+     *   console.log(guide.name, guide.guide_steps.length);
+     * }
+     * ```
+     */
+    getGuide(slugOrId: string): Promise<Guide | null>;
+    /**
+     * Track a guide analytics event.
+     * Used to track user progress through guides.
+     *
+     * @param event - Guide analytics event
+     *
+     * @example
+     * ```typescript
+     * await census.trackGuideEvent({
+     *   guideId: 'guide_123',
+     *   eventType: 'step_completed',
+     *   stepId: 'step_456',
+     *   stepIndex: 2,
+     *   sessionId: 'session_789',
+     * });
+     * ```
+     */
+    trackGuideEvent(event: GuideAnalyticsEvent): Promise<void>;
+    /**
+     * Mark a guide as completed for the current user.
+     * Prevents the guide from showing again.
+     *
+     * @param guideId - ID of the guide to mark as completed
+     *
+     * @example
+     * ```typescript
+     * await census.markGuideCompleted('guide_123');
+     * ```
+     */
+    markGuideCompleted(guideId: string): Promise<void>;
     /**
      * Get the current identified user ID
      */
@@ -768,7 +973,7 @@ declare function useArticle(slugOrId: string): {
  * @example
  * ```tsx
  * function MyRequests() {
- *   const { requests, isLoading, error, refetch } = useRequests();
+ *   const { requests, isLoading, error, refetch, settings } = useRequests();
  *
  *   if (isLoading) return <p>Loading...</p>;
  *   if (error) return <p>Error: {error.message}</p>;
@@ -791,10 +996,44 @@ declare function useRequests(options?: RequestsOptions): {
         offset: number;
         hasMore: boolean;
     } | undefined;
+    settings: RequestsSettings;
     isLoading: boolean;
     error: Error | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Hook for voting on requests.
+ *
+ * @returns Object with vote function and loading state
+ *
+ * @example
+ * ```tsx
+ * function VoteButton({ feedbackId }: { feedbackId: string }) {
+ *   const { vote, isVoting } = useVote();
+ *
+ *   const handleVote = async () => {
+ *     const result = await vote(feedbackId);
+ *     console.log('Voted:', result.action); // 'added' or 'removed'
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleVote} disabled={isVoting}>
+ *       Vote
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useVote(): {
+    vote: (feedbackId: string) => Promise<{
+        success: boolean;
+        action: "added" | "removed";
+        vote_count: number;
+        user_has_voted: boolean;
+    }>;
+    isVoting: boolean;
+    error: Error | null;
+};
 /**
  * Hook for tracking events.
  *
@@ -822,6 +1061,37 @@ declare function useTrack(): {
         properties?: Record<string, unknown>;
     }>) => Promise<void>;
 };
+/**
+ * Hook for fetching feature groups with their features.
+ *
+ * @returns Object with feature groups data and loading state
+ *
+ * @example
+ * ```tsx
+ * function FeatureNav() {
+ *   const { featureGroups, isLoading, error } = useFeatureGroups();
+ *
+ *   if (isLoading) return <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return (
+ *     <ul>
+ *       {featureGroups.map(group => (
+ *         <li key={group.id}>
+ *           {group.name} ({group.feature_count} features)
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useFeatureGroups(): {
+    featureGroups: FeatureGroup[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
 
 /**
  * Floating feedback button component.
@@ -889,4 +1159,4 @@ declare function KnowledgeBase({ showSearch, showCategories, defaultCategory, th
  */
 declare function Requests({ status, type, limit, className, showEmptyState, onRequestClick, }: RequestsProps): react_jsx_runtime.JSX.Element | null;
 
-export { type Article, type ArticlesOptions, CensusProvider, type CensusProviderProps, type CensusTheme, FeedbackButton, type FeedbackButtonProps, type FeedbackOptions, type FeedbackType, KnowledgeBase, type KnowledgeBaseProps, type Position, type Request, Requests, type RequestsOptions, type RequestsProps, type UserIdentity, useArticle, useArticles, useCensus, useCensusContext, useFeedback, useIdentify, useRequests, useTrack };
+export { type Article, type ArticlesOptions, CensusProvider, type CensusProviderProps, type CensusTheme, type Feature, type FeatureGroup, FeedbackButton, type FeedbackButtonProps, type FeedbackOptions, type FeedbackType, type FeedbackVisibility, KnowledgeBase, type KnowledgeBaseProps, type Position, type Request, Requests, type RequestsOptions, type RequestsProps, type RequestsSettings, type UserIdentity, useArticle, useArticles, useCensus, useCensusContext, useFeatureGroups, useFeedback, useIdentify, useRequests, useTrack, useVote };

package/dist/react/index.d.ts

@@ -188,6 +188,21 @@ interface Request {
     rating: number | null;
     helpful: boolean | null;
     metadata: Record<string, unknown>;
+    vote_count: number;
+    user_has_voted: boolean;
+    is_own: boolean;
+}
+/**
+ * Feedback visibility setting
+ */
+type FeedbackVisibility = 'own' | 'organization' | 'all';
+/**
+ * Project settings for requests
+ */
+interface RequestsSettings {
+    feedbackVisibility: FeedbackVisibility;
+    allowVoting: boolean;
+    allowRequestCreation: boolean;
 }
 /**
  * Options for fetching requests
@@ -223,6 +238,7 @@ interface RequestsResponse {
         offset: number;
         hasMore: boolean;
     };
+    settings: RequestsSettings;
 }
 /**
  * Position for floating UI elements
@@ -389,6 +405,99 @@ interface CensusProviderProps {
      */
     children: React.ReactNode;
 }
+interface GuideStep {
+    id: string;
+    sort_order: number;
+    selector_strategy: SelectorStrategy;
+    title: string | null;
+    content: string | null;
+    tooltip_position: TooltipPosition;
+    actions: GuideAction[];
+    wait_for: WaitForType;
+    wait_config: Record<string, unknown>;
+}
+interface SelectorStrategy {
+    css?: string;
+    xpath?: string;
+    text?: string;
+    testId?: string;
+}
+type TooltipPosition = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+type WaitForType = 'click' | 'next_button' | 'delay' | 'custom';
+interface GuideAction {
+    type: 'click' | 'input' | 'navigate' | 'custom';
+    config: Record<string, unknown>;
+}
+interface Guide {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    trigger_type: GuideTriggerType;
+    trigger_config: TriggerConfig;
+    theme: GuideTheme;
+    allow_skip: boolean;
+    show_progress: boolean;
+    guide_steps: GuideStep[];
+}
+type GuideTriggerType = 'manual' | 'url_match' | 'first_visit' | 'event';
+interface TriggerConfig {
+    url_pattern?: string;
+    event_name?: string;
+    delay_ms?: number;
+}
+interface GuideTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+}
+interface GuidesResponse {
+    guides: Guide[];
+    completedGuides: string[];
+}
+type GuideEventType = 'started' | 'step_viewed' | 'step_completed' | 'completed' | 'skipped' | 'dismissed';
+/**
+ * A feature within a feature group
+ */
+interface Feature {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: string;
+    article_count: number;
+}
+/**
+ * A group of related features
+ */
+interface FeatureGroup {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    color: string | null;
+    features: Feature[];
+    feature_count: number;
+    article_count: number;
+}
+/**
+ * Response from feature groups endpoint
+ */
+interface FeatureGroupsResponse {
+    feature_groups: FeatureGroup[];
+}
+interface GuideAnalyticsEvent {
+    guideId: string;
+    eventType: GuideEventType;
+    stepId?: string;
+    stepIndex?: number;
+    pageUrl?: string;
+    sessionId: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
 
 /**
  * Census SDK Client
@@ -500,6 +609,21 @@ declare class CensusClient {
      * ```
      */
     getArticle(slugOrId: string): Promise<Article | null>;
+    /**
+     * Fetch feature groups with their features and article counts.
+     * Used for navigation in the knowledge base.
+     *
+     * @returns Feature groups with nested features
+     *
+     * @example
+     * ```typescript
+     * const { feature_groups } = await census.getFeatureGroups();
+     * feature_groups.forEach(group => {
+     *   console.log(group.name, group.features.length);
+     * });
+     * ```
+     */
+    getFeatureGroups(): Promise<FeatureGroupsResponse>;
     /**
      * Fetch the current user's submitted requests (feedback, bugs, feature requests).
      * Requires a user to be identified first.
@@ -520,6 +644,29 @@ declare class CensusClient {
      * ```
      */
     getRequests(options?: RequestsOptions): Promise<RequestsResponse>;
+    /**
+     * Vote on a feedback request (toggle).
+     * If the user has already voted, removes the vote.
+     * If the user hasn't voted, adds a vote.
+     *
+     * @param feedbackId - ID of the feedback to vote on
+     * @returns Vote result with action taken and new vote count
+     *
+     * @example
+     * ```typescript
+     * // Vote on a feedback request
+     * const result = await census.vote('feedback-id-123');
+     * console.log(result.action); // 'added' or 'removed'
+     * console.log(result.vote_count); // 5
+     * console.log(result.user_has_voted); // true
+     * ```
+     */
+    vote(feedbackId: string): Promise<{
+        success: boolean;
+        action: 'added' | 'removed';
+        vote_count: number;
+        user_has_voted: boolean;
+    }>;
     /**
      * Track a custom analytics event.
      *
@@ -553,6 +700,64 @@ declare class CensusClient {
      * ```
      */
     trackBatch(options: BatchEventsOptions): Promise<void>;
+    /**
+     * Fetch available guides for the current user.
+     * Returns guides that match the user's context and haven't been completed.
+     *
+     * @returns Guides and list of completed guide IDs
+     *
+     * @example
+     * ```typescript
+     * const { guides, completedGuides } = await census.getGuides();
+     * guides.forEach(guide => console.log(guide.name));
+     * ```
+     */
+    getGuides(): Promise<GuidesResponse>;
+    /**
+     * Fetch a single guide by slug or ID.
+     *
+     * @param slugOrId - Guide slug or ID
+     * @returns Guide or null if not found
+     *
+     * @example
+     * ```typescript
+     * const guide = await census.getGuide('onboarding-tour');
+     * if (guide) {
+     *   console.log(guide.name, guide.guide_steps.length);
+     * }
+     * ```
+     */
+    getGuide(slugOrId: string): Promise<Guide | null>;
+    /**
+     * Track a guide analytics event.
+     * Used to track user progress through guides.
+     *
+     * @param event - Guide analytics event
+     *
+     * @example
+     * ```typescript
+     * await census.trackGuideEvent({
+     *   guideId: 'guide_123',
+     *   eventType: 'step_completed',
+     *   stepId: 'step_456',
+     *   stepIndex: 2,
+     *   sessionId: 'session_789',
+     * });
+     * ```
+     */
+    trackGuideEvent(event: GuideAnalyticsEvent): Promise<void>;
+    /**
+     * Mark a guide as completed for the current user.
+     * Prevents the guide from showing again.
+     *
+     * @param guideId - ID of the guide to mark as completed
+     *
+     * @example
+     * ```typescript
+     * await census.markGuideCompleted('guide_123');
+     * ```
+     */
+    markGuideCompleted(guideId: string): Promise<void>;
     /**
      * Get the current identified user ID
      */
@@ -768,7 +973,7 @@ declare function useArticle(slugOrId: string): {
  * @example
  * ```tsx
  * function MyRequests() {
- *   const { requests, isLoading, error, refetch } = useRequests();
+ *   const { requests, isLoading, error, refetch, settings } = useRequests();
  *
  *   if (isLoading) return <p>Loading...</p>;
  *   if (error) return <p>Error: {error.message}</p>;
@@ -791,10 +996,44 @@ declare function useRequests(options?: RequestsOptions): {
         offset: number;
         hasMore: boolean;
     } | undefined;
+    settings: RequestsSettings;
     isLoading: boolean;
     error: Error | null;
     refetch: () => Promise<void>;
 };
+/**
+ * Hook for voting on requests.
+ *
+ * @returns Object with vote function and loading state
+ *
+ * @example
+ * ```tsx
+ * function VoteButton({ feedbackId }: { feedbackId: string }) {
+ *   const { vote, isVoting } = useVote();
+ *
+ *   const handleVote = async () => {
+ *     const result = await vote(feedbackId);
+ *     console.log('Voted:', result.action); // 'added' or 'removed'
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleVote} disabled={isVoting}>
+ *       Vote
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useVote(): {
+    vote: (feedbackId: string) => Promise<{
+        success: boolean;
+        action: "added" | "removed";
+        vote_count: number;
+        user_has_voted: boolean;
+    }>;
+    isVoting: boolean;
+    error: Error | null;
+};
 /**
  * Hook for tracking events.
  *
@@ -822,6 +1061,37 @@ declare function useTrack(): {
         properties?: Record<string, unknown>;
     }>) => Promise<void>;
 };
+/**
+ * Hook for fetching feature groups with their features.
+ *
+ * @returns Object with feature groups data and loading state
+ *
+ * @example
+ * ```tsx
+ * function FeatureNav() {
+ *   const { featureGroups, isLoading, error } = useFeatureGroups();
+ *
+ *   if (isLoading) return <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return (
+ *     <ul>
+ *       {featureGroups.map(group => (
+ *         <li key={group.id}>
+ *           {group.name} ({group.feature_count} features)
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useFeatureGroups(): {
+    featureGroups: FeatureGroup[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
 
 /**
  * Floating feedback button component.
@@ -889,4 +1159,4 @@ declare function KnowledgeBase({ showSearch, showCategories, defaultCategory, th
  */
 declare function Requests({ status, type, limit, className, showEmptyState, onRequestClick, }: RequestsProps): react_jsx_runtime.JSX.Element | null;
 
-export { type Article, type ArticlesOptions, CensusProvider, type CensusProviderProps, type CensusTheme, FeedbackButton, type FeedbackButtonProps, type FeedbackOptions, type FeedbackType, KnowledgeBase, type KnowledgeBaseProps, type Position, type Request, Requests, type RequestsOptions, type RequestsProps, type UserIdentity, useArticle, useArticles, useCensus, useCensusContext, useFeedback, useIdentify, useRequests, useTrack };
+export { type Article, type ArticlesOptions, CensusProvider, type CensusProviderProps, type CensusTheme, type Feature, type FeatureGroup, FeedbackButton, type FeedbackButtonProps, type FeedbackOptions, type FeedbackType, type FeedbackVisibility, KnowledgeBase, type KnowledgeBaseProps, type Position, type Request, Requests, type RequestsOptions, type RequestsProps, type RequestsSettings, type UserIdentity, useArticle, useArticles, useCensus, useCensusContext, useFeatureGroups, useFeedback, useIdentify, useRequests, useTrack, useVote };