Home Insight AI SDK

Embeddable AI chat widget for real estate applications. Analyzes home inspections, loan documents, and provides instant answers with citations.

Features

• One-line integration - Drop in a single React component
• Document analysis - Understands inspection reports, loan estimates, closing disclosures
• Citation support - Every answer includes source references with page numbers
• Customizable - Two layout modes (popup/sidebar), custom brand colors, light/dark themes
• Mobile responsive - Works on all screen sizes

Installation

npm install home-insight-ai-sdk

Quick Start

Property-Level Chat (Recommended)

Chat across ALL documents for a property:

import { HomeInsightChat } from 'home-insight-ai-sdk';
import 'home-insight-ai-sdk/style.css';

function App() {
  return (
    <HomeInsightChat
      apiKey="hi_live_your_api_key"
      propertyId="prop_abc123"
      propertyAddress="123 Oak St, Austin, TX"
      layout="popup"           // or "sidebar" for full-height
      primaryColor="#5b7cff"   // Your brand color
    />
  );
}

Single Document Chat (Backward Compatible)

Chat with one document:

<HomeInsightChat
  apiKey="hi_live_your_api_key"
  analysisId="ana_xyz789"
/>

Upload Fallback

If no propertyId or analysisId is provided, allow users to upload files:

<HomeInsightChat
  apiKey="hi_live_your_api_key"
  allowUpload={true}  // ← Shows upload UI when no propertyId/analysisId
  propertyAddress="123 Main St, Austin, TX"  // Optional: pre-fill address
/>

Perfect for users who don't have existing properties yet! The SDK automatically shows the upload interface, allowing users to drag & drop documents and start chatting immediately.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiKey | string | Yes | - | Your Home Insight AI API key | | propertyId | string | No | - | Property ID - chat across ALL documents (recommended) | | analysisId | string | No | - | Analysis ID - chat with single document (backward compatible) | | preUploadedFiles | string[] | No | - | Array of file URLs to analyze | | propertyAddress | string | No | - | Property address for context | | layout | 'popup' \| 'sidebar' | No | 'popup' | Widget layout mode | | position | 'bottom-right' \| 'bottom-left' | No | 'bottom-right' | Widget position (popup mode) | | theme | 'light' \| 'dark' | No | 'light' | Color theme | | primaryColor | string | No | '#5b7cff' | Primary brand color (hex) | | accentColor | string | No | '#4a63d9' | Accent color for hover states (hex) | | apiBaseUrl | string | No | 'https://api.homeinsightai.com/v1' | API base URL | | allowUpload | boolean | No | true | Allow file upload in widget |

Note: Provide either propertyId (recommended for multi-document chat) OR analysisId (single document).

Usage Examples

Property-Level Chat (Recommended)

Chat across multiple documents for a property:

<HomeInsightChat
  apiKey="hi_live_abc123"
  propertyId="prop_abc456"
  propertyAddress="456 Maple Ave, Denver, CO"
/>

Benefits:

• Single widget for entire property
• Chat searches ALL documents simultaneously
• Citations from any document (inspection, loan, disclosures, etc.)
• Better UX for properties with 5-10+ documents

Single Document Chat (Backward Compatible)

If you've already created an analysis via the REST API:

<HomeInsightChat
  apiKey="hi_live_abc123"
  analysisId="ana_xyz789"
  propertyAddress="789 Pine Rd, Seattle, WA"
/>

Dark Theme

<HomeInsightChat
  apiKey="hi_live_abc123"
  analysisId="ana_xyz789"
  theme="dark"
  position="bottom-left"
/>

Sidebar Layout (Full-Height)

Perfect for property listing pages where chat is the primary feature:

<HomeInsightChat
  apiKey="hi_live_abc123"
  propertyId="prop_abc456"
  layout="sidebar"
  propertyAddress="123 Main St, Austin, TX"
/>

Features:

• 400px width, full screen height
• Click bubble to toggle open/close
• More space for chat history
• Mobile responsive (full width on phones)

Recommended for: Property detail pages, home inspection report viewers, dedicated chat/support pages

Custom Brand Colors

Match your site's brand colors:

<HomeInsightChat
  apiKey="hi_live_abc123"
  propertyId="prop_abc456"
  primaryColor="#10b981"  // Your brand color
  accentColor="#059669"   // Darker shade for hover states
/>

Color Examples:

• Green: primaryColor="#10b981" accentColor="#059669"
• Purple: primaryColor="#8b5cf6" accentColor="#7c3aed"
• Orange: primaryColor="#f59e0b" accentColor="#d97706"
• Red: primaryColor="#ef4444" accentColor="#dc2626"

Tips:

• Use hex color codes (e.g., #10b981)
• Accent color should be slightly darker for hover states
• Test colors against white text for accessibility (WCAG AA: 4.5:1 contrast)

Custom API URL (Self-hosted)

<HomeInsightChat
  apiKey="hi_live_abc123"
  analysisId="ana_xyz789"
  apiBaseUrl="https://your-server.com/v1"
/>

Styling

The widget comes with default styles. Import them in your app:

import 'home-insight-ai-sdk/style.css';

Custom Brand Colors (Recommended)

Use the primaryColor and accentColor props to match your brand:

<HomeInsightChat
  apiKey="hi_live_abc123"
  propertyId="prop_abc456"
  primaryColor="#10b981"  // Your brand color
  accentColor="#059669"   // Darker shade for hover states
/>

Colors are applied using CSS custom properties, affecting:

• Header background gradient
• Toggle button
• Send button
• Links and interactive elements
• Progress indicators

Advanced CSS Customization

For more control, override CSS classes (all prefixed with hi-chat-):

/* Custom toggle button positioning */
.hi-chat-toggle {
  bottom: 40px;
  right: 40px;
}

/* Override primary color via CSS variable */
.hi-chat-container {
  --hi-primary-color: #your-brand-color;
  --hi-accent-color: #your-accent-color;
}

/* Custom message bubbles */
.hi-chat-user {
  background: #your-brand-color;
}

For complete customization documentation, see CUSTOMIZATION.md

API Key

Get your API key at https://homeinsightai.com

⚠️ Security: Use Publishable Keys Only

IMPORTANT: When using this SDK in client-side code, you MUST use a publishable API key, NOT a secret key.

Key Types

| Type | Format | Usage | Security | |------|--------|-------|----------| | Secret Key | hi_live_secret_... | Backend only | ❌ Never expose in frontend | | Publishable Key | hi_live_pub_... | Frontend safe | ✅ Safe to embed in SDK |

Why Use Publishable Keys?

• ✅ Domain-restricted: Only works from your specified domains
• ✅ Limited permissions: Read-only access to chat endpoint
• ✅ Cannot modify data: Cannot create/delete properties or documents
• ✅ Cannot access billing: Cannot view or modify subscription info

How to Create a Publishable Key

curl -X POST https://api.homeinsightai.com/v1/api-keys/publishable \
  -H "Authorization: Bearer hi_live_secret_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Website",
    "allowed_domains": [
      "https://yourdomain.com",
      "https://www.yourdomain.com"
    ],
    "permissions": {
      "chat": true,
      "read_properties": true,
      "write_properties": false,
      "billing": false
    }
  }'

Response:

{
  "id": "key_abc123",
  "key": "hi_live_pub_XyZ789...",
  "key_type": "publishable",
  "allowed_domains": ["https://yourdomain.com"],
  "permissions": {"chat": true, "read_properties": true}
}

Copy the key value and use it in your SDK:

<HomeInsightChat
  apiKey="hi_live_pub_XyZ789..."  // ✅ Publishable key
  propertyId="prop_abc123"
/>

Subscription Tiers

| Tier | Price | Analyses | Chat Messages | |------|-------|----------|---------------| | Free | $0 | 1/month | 50/month | | Starter | $29/mo | 10/month | Unlimited | | Pro | $99/mo | 100/month | Unlimited | | Enterprise | Contact | Unlimited | Unlimited |

Migration Guide

Upgrading to Property-Level Chat

Before (Single Document):

{documents.map(doc => (
  <HomeInsightChat
    key={doc.id}
    apiKey="hi_live_abc123"
    analysisId={doc.id}
  />
))}

After (Property-Level - Recommended):

<HomeInsightChat
  apiKey="hi_live_abc123"
  propertyId={property.id}
  propertyAddress={property.address}
/>

Benefits of Migration:

• Embed ONE widget instead of multiple
• Users can ask questions across ALL documents
• Better performance (one WebSocket connection)
• Cleaner UI/UX

REST API

For server-side integration, use our REST API directly:

# Create property
curl -X POST https://api.homeinsightai.com/v1/properties \
  -H "Authorization: Bearer hi_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Main St, Austin, TX"}'

# Upload documents to property
curl -X POST https://api.homeinsightai.com/v1/properties/prop_abc456/upload \
  -H "Authorization: Bearer hi_live_abc123" \
  -F "[email protected]" \
  -F "files=@loan_estimate.pdf"

# Chat with property (searches all documents)
curl -X POST https://api.homeinsightai.com/v1/chat \
  -H "Authorization: Bearer hi_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "What issues were found with the roof?", "property_id": "prop_abc456"}'

TypeScript Support

Full TypeScript support included:

import { HomeInsightChat, HomeInsightChatProps } from 'home-insight-ai-sdk';

const props: HomeInsightChatProps = {
  apiKey: 'hi_live_abc123',
  theme: 'dark',
  position: 'bottom-right'
};

<HomeInsightChat {...props} />

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Support

• Documentation: https://docs.homeinsightai.com
• Email: [email protected]
• GitHub Issues: https://github.com/homeinsight-ai/sdk/issues

License

MIT