@census-ai/census-sdk 0.2.0 → 0.4.1

package/dist/index.d.cts

@@ -103,7 +103,7 @@ interface Article {
     read_time_minutes: number | null;
     published_at: string | null;
     sort_order: number;
-    content?: unknown;
+    content?: string;
     content_html?: string;
     features?: {
         id: string;
@@ -111,6 +111,36 @@ interface Article {
         slug: string;
     };
 }
+/**
+ * A feature within a feature group
+ */
+interface Feature {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: string;
+    article_count: number;
+}
+/**
+ * A feature group containing 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[];
+}
 /**
  * Options for fetching articles
  */
@@ -229,6 +259,272 @@ interface CensusError {
     error: string;
     status?: number;
 }
+/**
+ * Step types for guides
+ */
+type GuideStepType = 'tooltip' | 'modal' | 'slideout' | 'hotspot' | 'banner';
+/**
+ * Tooltip position options
+ */
+type TooltipPosition = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Step advancement trigger types
+ */
+type AdvanceTrigger = 'button' | 'click' | 'delay' | 'form-submit';
+/**
+ * Form types for guide steps
+ */
+type GuideFormType = 'nps' | 'rating' | 'text' | 'select' | 'multi-select';
+/**
+ * Rich content for guide steps
+ */
+interface GuideStepRichContent {
+    title?: string;
+    body?: string;
+    media?: {
+        type: 'image' | 'video';
+        url: string;
+        alt?: string;
+    };
+    buttons?: Array<{
+        label: string;
+        action: 'next' | 'prev' | 'dismiss' | 'url' | 'custom';
+        url?: string;
+        customAction?: string;
+        style?: 'primary' | 'secondary' | 'text';
+    }>;
+    form?: {
+        type: GuideFormType;
+        question: string;
+        options?: string[];
+        required?: boolean;
+        submitLabel?: string;
+    };
+}
+/**
+ * Display configuration for guide steps
+ */
+interface GuideStepDisplayConfig {
+    position?: TooltipPosition | 'center';
+    offset?: {
+        x: number;
+        y: number;
+    };
+    width?: number;
+    backdrop?: boolean;
+    spotlightPadding?: number;
+    bannerPosition?: 'top' | 'bottom';
+}
+/**
+ * Advancement configuration for guide steps
+ */
+interface GuideStepAdvanceConfig {
+    trigger: AdvanceTrigger;
+    delay?: number;
+    clickSelector?: string;
+}
+/**
+ * Style configuration for guide steps
+ */
+interface GuideStepStyleConfig {
+    backgroundColor?: string;
+    textColor?: string;
+    accentColor?: string;
+    borderRadius?: number;
+    customCSS?: string;
+}
+/**
+ * Selector strategy for targeting elements
+ */
+interface SelectorStrategy {
+    css?: string;
+    xpath?: string;
+    text?: string;
+    testId?: string;
+}
+/**
+ * Guide step definition
+ */
+interface GuideStep {
+    id: string;
+    guide_id?: string;
+    sort_order: number;
+    step_type: GuideStepType;
+    selector_strategy: SelectorStrategy | null;
+    title: string | null;
+    content: string | null;
+    tooltip_position: TooltipPosition;
+    actions: Array<Record<string, unknown>>;
+    wait_for: 'click' | 'next_button' | 'delay' | 'custom';
+    wait_config: Record<string, unknown>;
+    rich_content: GuideStepRichContent;
+    display_config: GuideStepDisplayConfig;
+    advance_config: GuideStepAdvanceConfig;
+    style_config: GuideStepStyleConfig;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * Guide trigger types
+ */
+type GuideTriggerType = 'manual' | 'url_match' | 'first_visit' | 'event';
+/**
+ * Guide status
+ */
+type GuideStatus = 'draft' | 'published' | 'archived';
+/**
+ * Guide definition
+ */
+interface Guide {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    trigger_type: GuideTriggerType;
+    trigger_config: Record<string, unknown>;
+    theme: Record<string, unknown>;
+    allow_skip: boolean;
+    show_progress: boolean;
+    status?: GuideStatus;
+    published_at?: string | null;
+    created_at?: string;
+    updated_at?: string;
+    guide_steps: GuideStep[];
+}
+/**
+ * Options for creating a guide
+ */
+interface CreateGuideOptions {
+    /**
+     * Name of the guide
+     */
+    name: string;
+    /**
+     * URL-friendly slug (lowercase, hyphens only)
+     */
+    slug: string;
+    /**
+     * Description of the guide
+     */
+    description?: string;
+    /**
+     * Project ID to associate with
+     */
+    projectId?: string;
+    /**
+     * When to trigger the guide
+     * @default "manual"
+     */
+    triggerType?: GuideTriggerType;
+    /**
+     * Configuration for the trigger (e.g., url_pattern for url_match)
+     */
+    triggerConfig?: Record<string, unknown>;
+    /**
+     * Theme customization
+     */
+    theme?: Record<string, unknown>;
+    /**
+     * Allow users to skip the guide
+     * @default true
+     */
+    allowSkip?: boolean;
+    /**
+     * Show progress indicator
+     * @default true
+     */
+    showProgress?: boolean;
+}
+/**
+ * Options for updating a guide
+ */
+interface UpdateGuideOptions {
+    name?: string;
+    slug?: string;
+    description?: string;
+    triggerType?: GuideTriggerType;
+    triggerConfig?: Record<string, unknown>;
+    theme?: Record<string, unknown>;
+    allowSkip?: boolean;
+    showProgress?: boolean;
+    status?: GuideStatus;
+}
+/**
+ * Options for creating a guide step
+ */
+interface CreateGuideStepOptions {
+    /**
+     * Type of step
+     * @default "tooltip"
+     */
+    stepType?: GuideStepType;
+    /**
+     * Order position (auto-assigned if not provided)
+     */
+    sortOrder?: number;
+    /**
+     * Element selector strategy
+     */
+    selectorStrategy?: SelectorStrategy;
+    /**
+     * Simple title (legacy, use richContent.title instead)
+     */
+    title?: string;
+    /**
+     * Simple content (legacy, use richContent.body instead)
+     */
+    content?: string;
+    /**
+     * Tooltip position
+     * @default "auto"
+     */
+    tooltipPosition?: TooltipPosition;
+    /**
+     * Rich content configuration
+     */
+    richContent?: GuideStepRichContent;
+    /**
+     * Display configuration
+     */
+    displayConfig?: GuideStepDisplayConfig;
+    /**
+     * Advancement configuration
+     */
+    advanceConfig?: GuideStepAdvanceConfig;
+    /**
+     * Style overrides
+     */
+    styleConfig?: GuideStepStyleConfig;
+}
+/**
+ * Options for updating a guide step
+ */
+interface UpdateGuideStepOptions extends Partial<CreateGuideStepOptions> {
+}
+/**
+ * Options for fetching guides
+ */
+interface GuidesOptions {
+    /**
+     * Filter by project ID
+     */
+    projectId?: string;
+    /**
+     * Current page URL (for trigger matching)
+     */
+    url?: string;
+    /**
+     * User ID (to get completion status)
+     */
+    userId?: string;
+}
+/**
+ * Response from guides list endpoint
+ */
+interface GuidesResponse {
+    guides: Guide[];
+    completedGuides: string[];
+}
 /**
  * Position for floating UI elements
  */
@@ -394,58 +690,6 @@ 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';
 interface GuideAnalyticsEvent {
     guideId: string;
@@ -457,15 +701,6 @@ interface GuideAnalyticsEvent {
     userId?: string;
     metadata?: Record<string, unknown>;
 }
-interface TooltipOptions {
-    position?: TooltipPosition;
-    showProgress?: boolean;
-    showSkip?: boolean;
-    onNext?: () => void;
-    onPrev?: () => void;
-    onSkip?: () => void;
-    onClose?: () => void;
-}
 
 /**
  * Census SDK Client
@@ -577,6 +812,21 @@ declare class CensusClient {
      * ```
      */
     getArticle(slugOrId: string): Promise<Article | null>;
+    /**
+     * Fetch feature groups with their features.
+     * Used by the HelpCenter component for navigation.
+     *
+     * @returns Feature groups with features and article counts
+     *
+     * @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.
@@ -631,33 +881,166 @@ 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.
+     * Get published guides.
      *
-     * @returns Guides and list of completed guide IDs
+     * @param options - Query options
+     * @returns Guides and completion status
      *
      * @example
      * ```typescript
-     * const { guides, completedGuides } = await census.getGuides();
-     * guides.forEach(guide => console.log(guide.name));
+     * const { guides, completedGuides } = await census.getGuides({
+     *   url: window.location.href,
+     *   userId: 'user_123',
+     * });
      * ```
      */
-    getGuides(): Promise<GuidesResponse>;
+    getGuides(options?: GuidesOptions): Promise<GuidesResponse>;
     /**
-     * Fetch a single guide by slug or ID.
+     * Get a single guide by ID.
      *
-     * @param slugOrId - Guide slug or ID
-     * @returns Guide or null if not found
+     * @param guideId - Guide ID
+     * @returns Guide with steps or null if not found
      *
      * @example
      * ```typescript
-     * const guide = await census.getGuide('onboarding-tour');
+     * const guide = await census.getGuide('guide_123');
      * if (guide) {
      *   console.log(guide.name, guide.guide_steps.length);
      * }
      * ```
      */
-    getGuide(slugOrId: string): Promise<Guide | null>;
+    getGuide(guideId: string): Promise<Guide | null>;
+    /**
+     * Create a new guide.
+     * Requires guides:create or guides:admin scope.
+     *
+     * @param options - Guide creation options
+     * @returns Created guide
+     *
+     * @example
+     * ```typescript
+     * const guide = await census.createGuide({
+     *   name: 'Welcome Tour',
+     *   slug: 'welcome-tour',
+     *   description: 'Introduction to the app',
+     *   triggerType: 'first_visit',
+     * });
+     * ```
+     */
+    createGuide(options: CreateGuideOptions): Promise<Guide>;
+    /**
+     * Update an existing guide.
+     * Requires guides:create or guides:admin scope.
+     *
+     * @param guideId - Guide ID to update
+     * @param options - Update options
+     * @returns Updated guide
+     *
+     * @example
+     * ```typescript
+     * const guide = await census.updateGuide('guide_123', {
+     *   name: 'Updated Tour Name',
+     *   status: 'published',
+     * });
+     * ```
+     */
+    updateGuide(guideId: string, options: UpdateGuideOptions): Promise<Guide>;
+    /**
+     * Delete a guide.
+     * Requires guides:admin scope.
+     *
+     * @param guideId - Guide ID to delete
+     *
+     * @example
+     * ```typescript
+     * await census.deleteGuide('guide_123');
+     * ```
+     */
+    deleteGuide(guideId: string): Promise<void>;
+    /**
+     * Get steps for a guide.
+     *
+     * @param guideId - Guide ID
+     * @returns Array of steps
+     *
+     * @example
+     * ```typescript
+     * const steps = await census.getGuideSteps('guide_123');
+     * ```
+     */
+    getGuideSteps(guideId: string): Promise<GuideStep[]>;
+    /**
+     * Add a step to a guide.
+     * Requires guides:create or guides:admin scope.
+     *
+     * @param guideId - Guide ID
+     * @param options - Step creation options
+     * @returns Created step
+     *
+     * @example
+     * ```typescript
+     * const step = await census.addGuideStep('guide_123', {
+     *   stepType: 'tooltip',
+     *   selectorStrategy: { css: '.welcome-button' },
+     *   richContent: {
+     *     title: 'Welcome!',
+     *     body: 'Click here to get started',
+     *   },
+     * });
+     * ```
+     */
+    addGuideStep(guideId: string, options: CreateGuideStepOptions): Promise<GuideStep>;
+    /**
+     * Update a guide step.
+     * Requires guides:create or guides:admin scope.
+     *
+     * @param guideId - Guide ID
+     * @param stepId - Step ID
+     * @param options - Update options
+     * @returns Updated step
+     *
+     * @example
+     * ```typescript
+     * const step = await census.updateGuideStep('guide_123', 'step_456', {
+     *   richContent: { title: 'Updated title' },
+     * });
+     * ```
+     */
+    updateGuideStep(guideId: string, stepId: string, options: UpdateGuideStepOptions): Promise<GuideStep>;
+    /**
+     * Delete a guide step.
+     * Requires guides:create or guides:admin scope.
+     *
+     * @param guideId - Guide ID
+     * @param stepId - Step ID
+     *
+     * @example
+     * ```typescript
+     * await census.deleteGuideStep('guide_123', 'step_456');
+     * ```
+     */
+    deleteGuideStep(guideId: string, stepId: string): Promise<void>;
+    /**
+     * Reorder steps in a guide.
+     * Requires guides:create or guides:admin scope.
+     *
+     * @param guideId - Guide ID
+     * @param stepOrder - Array of { id, sort_order } to define new order
+     * @returns Updated steps
+     *
+     * @example
+     * ```typescript
+     * const steps = await census.reorderGuideSteps('guide_123', [
+     *   { id: 'step_a', sort_order: 0 },
+     *   { id: 'step_b', sort_order: 1 },
+     *   { id: 'step_c', sort_order: 2 },
+     * ]);
+     * ```
+     */
+    reorderGuideSteps(guideId: string, stepOrder: Array<{
+        id: string;
+        sort_order: number;
+    }>): Promise<GuideStep[]>;
     /**
      * Track a guide analytics event.
      * Used to track user progress through guides.
@@ -723,4 +1106,4 @@ declare class CensusClient {
  */
 declare function createCensus(config: CensusConfig): CensusClient;
 
-export { type Article, type ArticlesOptions, type ArticlesResponse, type BatchEventsOptions, CensusClient, type CensusConfig, type CensusError, type CensusProviderProps, type CensusTheme, type FeedbackButtonProps, type FeedbackOptions, type FeedbackType, type Guide, type GuideAction, type GuideAnalyticsEvent, type GuideEventType, type GuideStep, type GuideTheme, type GuideTriggerType, type GuidesResponse, type KnowledgeBaseProps, type Position, type Request, type RequestsOptions, type RequestsProps, type RequestsResponse, type SelectorStrategy, type TooltipOptions, type TooltipPosition, type TrackEventOptions, type TriggerConfig, type UserIdentity, type WaitForType, createCensus };
+export { type AdvanceTrigger, type Article, type ArticlesOptions, type ArticlesResponse, type BatchEventsOptions, CensusClient, type CensusConfig, type CensusError, type CensusProviderProps, type CensusTheme, type CreateGuideOptions, type CreateGuideStepOptions, type FeedbackButtonProps, type FeedbackOptions, type FeedbackType, type Guide, type GuideAnalyticsEvent, type GuideEventType, type GuideFormType, type GuideStatus, type GuideStep, type GuideStepAdvanceConfig, type GuideStepDisplayConfig, type GuideStepRichContent, type GuideStepStyleConfig, type GuideStepType, type GuideTriggerType, type GuidesOptions, type GuidesResponse, type KnowledgeBaseProps, type Position, type Request, type RequestsOptions, type RequestsProps, type RequestsResponse, type SelectorStrategy, type TooltipPosition, type TrackEventOptions, type UpdateGuideOptions, type UpdateGuideStepOptions, type UserIdentity, createCensus };