npm package: @legitify/sdk
Description: Wake your Business up. Embed intelligent assistance into your React/Next.js app.
Author: Legitify
Latest version: 1.0.1

# @legitify/sdk

**Wake your Business up.** Embed intelligent assistance into your React/Next.js application.

[![npm version](https://badge.fury.io/js/@legitify%2Fsdk.svg)](https://www.npmjs.com/package/@legitify/sdk)

## What is Legitify?

Legitify makes your app "alive" — giving it a voice that can guide users, answer questions, and take action. Your customers press and hold your logo, your Business awakens, and helps them succeed.

**No AI expertise needed. No separate AI billing. Just your Business, awakened.**

---

## ✨ Features

- 🎯 **Logo Hold Activation** — Press and hold your app's logo for 2 seconds
- 💬 **Natural Conversation** — Users ask naturally, your Business responds intelligently  
- 🧭 **Context-Aware** — Knows what page they're on and what they need
- 🛠️ **Built-in Tools** — Navigate, highlight elements, show tooltips
- 👤 **Role-Based** — Different capabilities for users vs admins
- 🎨 **Customizable** — Match your brand colors and styling
- 🔒 **Secure** — All intelligence handled by Legitify's backend

---

## 🚀 Quick Start

### 1. Install

```bash
npm install @legitify/sdk
```

### 2. Get Your API Key

Sign up at [legitimizeai.com](https://www.legitimizeai.com) and copy your API key from the dashboard.

### 3. Wrap Your App

```tsx
import { SentienceProvider } from "@legitify/sdk";

function App() {
  return (
    <SentienceProvider
      legitifyApiKey={process.env.NEXT_PUBLIC_LEGITIFY_API_KEY}
      user={currentUser}
      config={{
        appName: "Your App",
        primaryColor: "#3b82f6",
      }}
    >
      {children}
    </SentienceProvider>
  );
}
```

### 4. Make Your Logo Sentient

```tsx
import { useRef } from "react";
import { useLogoSentience, LogoProgressRing } from "@legitify/sdk";

export function Logo() {
  const logoRef = useRef(null);
  const { holdProgress, isHolding } = useLogoSentience(logoRef);

  return (
    <div ref={logoRef} className="relative">
      <div className="text-xl font-bold">YourApp</div>
      {isHolding && (
        <LogoProgressRing progress={holdProgress} size={60} />
      )}
    </div>
  );
}
```

**That's it.** Your users can now press and hold your logo to talk to your Business.

---

## 📖 Usage

### SentienceProvider Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `legitifyApiKey` | `string` | ✅ | Your Legitify API key |
| `user` | `object` | ✅ | Current user object (with `id`, `name`, `email`) |
| `config` | `object` | | App configuration (see below) |

### Configuration Options

```tsx
const config = {
  appName: "Your App Name",
  description: "What your app does",
  primaryColor: "#3b82f6",
  welcomeMessage: "How can I help you today?",
};
```

### User Roles

Your user's role is automatically detected from their metadata:

```tsx
// Clerk example
user.publicMetadata.role === "admin" // Admin access
user.publicMetadata.role === "user"  // User access
```

**Admin users get:** Analytics tools, user management, configuration access  
**Regular users get:** Navigation help, UI guidance, general support

---

## 🎨 Styling

The SDK uses Tailwind CSS classes. It will inherit your app's styles automatically.

To customize the primary color:

```tsx
<SentienceProvider
  config={{ primaryColor: "#your-brand-color" }}
  // ...
>
```

---

## 🔐 Security

- Your API key is sent securely to Legitify's backend
- All AI processing happens on our servers — never exposed to users
- We handle provider fallbacks, rate limits, and optimizations
- You get a simple, clean API

---

## 💰 Pricing

| Tier | Price | Interactions | Best For |
|------|-------|--------------|----------|
| **Free** | $0 | 100/mo | Trying it out |
| **Pro** | $49/mo | 10K/mo | Growing apps |
| **Enterprise** | $299/mo | Unlimited | Large teams |

[View full pricing →](https://www.legitimizeai.com/pricing)

---

## 🛠️ Custom Tools (Pro+)

Define custom actions your Business can perform:

```tsx
// Coming soon — register custom tools for your Business
```

---

## 📚 Examples

### SaaS Dashboard
```
User: "Show me this month's churned customers"
Business: "Here's your churn report for February — 12 customers, down 5% from January..."
```

### E-commerce
```
User: "Help me find a gift for my mom"
Business: "I'd recommend these products based on popular gift categories..."
```

### Internal Tools
```
User: "Approve pending expense reports"
Business: "You have 3 pending reports. Here they are..."
```

---

## 🐛 Troubleshooting

**"I'm not connected yet"**
- Check that your `legitifyApiKey` is correct
- Verify the user object is passed correctly

**Chat doesn't open**
- Make sure the logo element has `position: relative`
- Check that `useLogoSentience` is called with a valid ref

**API errors**
- Check your usage limits in the dashboard
- Verify your API key hasn't been revoked

---

## 📄 License

MIT © [Legitify](https://www.legitimizeai.com)

---

## 💬 Support

- Documentation: [legitimizeai.com/docs](https://www.legitimizeai.com/docs)
- Email: support@legitimizeai.com
- Dashboard: [legitimizeai.com/app](https://www.legitimizeai.com/app)

**Wake your Business up.**