npm package: @prodact.ai/sdk
Description: Interactive SDK for Prodact.ai - AI-powered UI interactions
Author: Viam
Latest version: 0.0.57

# @viam/sdk

Interactive SDK for Viam - AI-powered UI interactions triggered by chat.

## Installation

```bash
npm install @viam/sdk
```

## Quick Start

### React

```tsx
import { ViamProvider, ViamChat, useViamAction } from '@viam/sdk/react';

function App() {
  return (
    <ViamProvider
      config={{
        guiderId: 'your-guider-id',
        apiUrl: 'https://api.viam.io/api/v1', // optional
      }}
    >
      <MyApp />
      <ViamChat position="bottom-right" />
    </ViamProvider>
  );
}

function ContactButton() {
  const [isOpen, setIsOpen] = useState(false);

  // Register action - when user asks "open contact modal", this triggers
  useViamAction('act_contact_xyz123', () => {
    setIsOpen(true);
  });

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Contact Us</button>
      {isOpen && <ContactModal onClose={() => setIsOpen(false)} />}
    </>
  );
}
```

### Using ViamTarget

Wrap elements to auto-highlight and scroll when triggered:

```tsx
import { ViamTarget } from '@viam/sdk/react';

function PricingSection() {
  return (
    <ViamTarget
      actionKey="act_pricing_abc123"
      onTrigger={() => console.log('User was directed to pricing!')}
    >
      <div className="pricing-section">
        <h2>Pricing</h2>
        {/* ... */}
      </div>
    </ViamTarget>
  );
}
```

### Vanilla JavaScript

```javascript
import { createViam } from '@viam/sdk';

const viam = createViam({
  guiderId: 'your-guider-id',
});

// Initialize
await viam.init();

// Register actions
viam.register('act_contact_xyz123', (payload) => {
  document.getElementById('contact-modal').classList.add('open');
});

// Send a message
const response = await viam.sendMessage('How do I contact support?');
// If message matches "contact" action, it will trigger automatically
```

## API Reference

### ViamProvider Props

| Prop | Type | Description |
|------|------|-------------|
| `config.guiderId` | `string` | Your Viam guider ID (required) |
| `config.apiUrl` | `string` | API URL (default: `http://localhost:4001/api/v1`) |
| `onAction` | `(key, payload) => void` | Called when any action is triggered |
| `onError` | `(error) => void` | Called on errors |

### ViamChat Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `'bottom-right' \| 'bottom-left' \| 'inline'` | `'bottom-right'` | Chat widget position |
| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
| `primaryColor` | `string` | `'#f97316'` | Primary accent color |
| `title` | `string` | `'Chat Assistant'` | Chat header title |
| `placeholder` | `string` | `'Ask a question...'` | Input placeholder |

### Hooks

#### `useViam()`
Returns the full Viam context with SDK instance, messages, and methods.

#### `useViamAction(actionKey, handler, deps?)`
Register an action handler that fires when the AI triggers this action.

#### `useViamMessages()`
Returns `{ messages, isLoading, sendMessage }` for building custom chat UIs.

#### `useViamReady()`
Returns `boolean` indicating if SDK is initialized.

### ViamTarget Props

| Prop | Type | Description |
|------|------|-------------|
| `actionKey` | `string` | The action key to respond to (required) |
| `onTrigger` | `(payload) => void` | Called when action is triggered |
| `highlightStyle` | `CSSProperties` | Custom highlight styles |
| `highlightDuration` | `number` | How long to highlight (ms, default: 3000) |
| `scrollIntoView` | `boolean` | Auto-scroll to element (default: true) |

## Setting Up Actions

1. Go to your Viam dashboard
2. Navigate to your Guider → SDK tab
3. Enable SDK integration
4. Create actions with trigger prompts:
   - Name: "Open Contact Modal"
   - Prompts: "contact support", "get in touch", "talk to someone"
5. Copy the generated action key (e.g., `act_contact_x7y8z9`)
6. Use the key in your code with `useViamAction` or `viam.register()`

## How It Works

1. User types a message in the chat
2. AI analyzes if message matches any configured SDK action
3. If matched, the registered handler is called
4. Chat displays a response confirming the action

## License

MIT