AI Insights Client

A React component library for AI-powered brand analysis and insights. This library provides a complete interface for brand analysis including setup wizard, analysis results, and settings management.

Installation

npm install ai-insights-client
# or
yarn add ai-insights-client

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

npm install react react-dom @yoast/ui-library

Note: React Router is bundled with this library to avoid version conflicts. You don't need to install it separately.

Basic Usage

Simple Embedded Component

import { AIInsightsClient } from 'ai-insights-client';
import 'ai-insights-client/dist/style.css';

function App() {
  return (
    <div className="my-app">
      <h1>My Application</h1>
      <AIInsightsClient
        routerType="memory"
        initialRoute="/"
        className="ai-insights-container"
      />
    </div>
  );
}

export default App;

With Custom Router Integration

import { BrowserRouter, Route, Routes } from 'react-router-dom';
import { AIInsightsClient } from 'ai-insights-client';
import 'ai-insights-client/dist/style.css';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route
          path="/insights/*"
          element={
            <AIInsightsClient routerType="memory" initialRoute="/setup" />
          }
        />
        <Route path="/" element={<HomePage />} />
      </Routes>
    </BrowserRouter>
  );
}

Component Props

AIInsightsClient

| Prop | Type | Default | Description | | -------------- | --------------------------------- | ----------- | ---------------------------------------------- | | routerType | 'browser' \| 'hash' \| 'memory' | 'memory' | Router type to use | | initialRoute | string | '/' | Initial route when using memory router | | isRtl | boolean | false | Whether the UI should be rendered in RTL mode | | className | string | undefined | Optional CSS class name for the root container | | style | React.CSSProperties | undefined | Optional inline styles for the root container |

Router Types

• memory (recommended for embedding): Uses React Router's MemoryRouter, which doesn't change the browser URL. Perfect for embedding in other applications.
• browser: Uses BrowserRouter for standalone applications with clean URLs.
• hash: Uses HashRouter for applications that need hash-based routing.

Available Routes

• / - Brand Analysis dashboard
• /setup - Setup wizard
• /setup/brand-summary - Brand summary step
• /setup/:brandId/queries - Query selection step
• /setup/:brandId/analysis - Analysis step
• /settings - Settings page
• /query-history - Query history
• /brand-list - Brand list

Advanced Usage

Using Individual Components

import {
  BrandAnalysisProvider,
  Layout,
  BrandAnalysis,
} from 'ai-insights-client';

function CustomApp() {
  return (
    <BrandAnalysisProvider>
      <Layout>
        <BrandAnalysis />
      </Layout>
    </BrandAnalysisProvider>
  );
}

Using Context Hooks

import {
  BrandAnalysisProvider,
  useBrandAnalysisData,
  useBrandAnalysisMutations,
} from 'ai-insights-client';

function CustomComponent() {
  const { brandId } = useBrandAnalysisData();
  const { setBrandId } = useBrandAnalysisMutations();

  return (
    <div>
      <h2>Current Brand ID: {brandId}</h2>
      <button onClick={() => setBrandId('new-brand-id')}>Set Brand ID</button>
    </div>
  );
}

function App() {
  return (
    <BrandAnalysisProvider>
      <CustomComponent />
    </BrandAnalysisProvider>
  );
}

Styling

The component comes with pre-built CSS that should be imported:

import 'ai-insights-client/dist/style.css';

The component uses Tailwind CSS with the yst- prefix. If you're using Tailwind in your project, you may need to configure your build to include the component's styles or import the CSS file as shown above.

Dev Mode (Preview Environments)

For testing purposes, the application includes a dev mode that allows manual token entry to bypass normal authentication. This feature is only available when the VITE_LOCALSTORAGE_AUTH environment variable is set to true.

When enabled, a "Dev mode token" section appears in the sidebar that provides a textarea for entering authentication tokens. Tokens are auto-saved after a 1-second debounce (there is no save button). This is useful for preview environments and testing scenarios.

API Integration with Orval

This project uses Orval to automatically generate type-safe API client code from our OpenAPI specification. This eliminates the need to manually write fetch or Axios calls and ensures our frontend stays in sync with backend API changes.

How Orval Works

Orval takes an OpenAPI specification file and converts it into TypeScript functions that can be consumed directly to perform API actions. The generated code includes:

• Typed Axios request functions
• TanStack Query hooks for data fetching
• TypeScript interfaces for request/response types
• Automatic error handling

Generated Code Location

The Orval output is generated into /src/api/generated/. While generated code typically wouldn't be committed to Git (like node_modules), we've chosen to commit these files to enable:

• Easy comparison of API changes during code review
• Tracking of API evolution over time
• Immediate availability for developers without requiring local generation

Development Workflow

Updating API Code

To pull the latest API changes from the backend:

# Pull from local development server (localhost:8000)
yarn orval:dev

# Pull from production/staging API
yarn orval:prod

Configuration can be found in orval.config.ts.

Code Review Guidelines

When reviewing changes in /src/api/generated/:

• Focus on high-level review to ensure new endpoints and schema changes are properly reflected
• Verify the changes align with the corresponding ai-insights-api branch
• Don't modify generated files directly - changes should come from API updates
• TypeScript compilation will catch most incompatibility issues

Best Practices

1. Always regenerate before merging: Run yarn orval:dev after the API branch merges to main to capture all changes
2. Coordinate with backend: Ensure the API branch is up-to-date when generating frontend code
3. Review systematically: Check that new endpoints, modified schemas, and removed endpoints are properly reflected

TypeScript Support

This library is built with TypeScript and includes full type definitions. All components and hooks are fully typed for the best development experience.

import type { AIInsightsClientProps, BrandAnalysisData } from 'ai-insights-client';

Contributing

[Add your contributing guidelines here]

License

MIT