@vlop/ai - Papavlop SDK

Papavlop is the native AI companion for Vlop. This package ships the floating chat widget, a lightweight API client, and helper types so you can drop Papavlop into any React surface - your main app, marketing pages, or partner integrations.

Installation

npm install @vlop/ai
# or
yarn add @vlop/ai

Papavlop expects you to manage API keys in Firebase. Approved users receive keys that start with vlop_, and the server routes in app/api/ai/* enforce token usage.

Quick Start

import { PapavlopChat } from '@vlop/ai'

export default function Example() {
  return (
    <PapavlopChat
      apiKey="vlop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      defaultOpen
    />
  )
}

The widget fetches its colors, launcher icon, greeting, and prompt from the Papavlop Studio API using the supplied key. You can override any part of the resolved configuration without disabling remote control:

<PapavlopChat
  apiKey="vlop_xxx"
  overrides={{
    launcher: { label: 'Ask Papavlop', icon: 'bot' },
    theme: { accentColor: '#38bdf8' }
  }}
/>

To render a preview (for example inside the Studio), bypass the remote lookup and pass the full config:

import { PapavlopChat, mergePapavlopConfig } from '@vlop/ai'

const config = mergePapavlopConfig({
  name: 'Papavlop',
  greeting: 'Preview: tweak settings in the Studio.',
  launcher: { label: 'Open Chat', icon: 'sparkles' }
})

<PapavlopChat apiKey="demo" useRemoteConfig={false} overrides={config} defaultOpen />

Papavlop streams responses over Server-Sent Events (SSE), keeps optimistic UI updates, and displays a subtle "Powered by Vlop" footer.

Remote Configuration

Papavlop Studio writes a botConfig document to vlopai_users/{uid}. The SDK merges that remote config with the defaults shown above and any overrides you pass at render time. Fields exposed in the Studio:

• name, tagline, greeting, inputPlaceholder
• position (bottom-right, bottom-left, top-right, top-left)
• Theme colors for accent, background, text, borders, and composer
• Launcher icon, label, optional icon URL, and button colors
• Full system prompt for the conversation

If Studio is unreachable, the widget falls back to the local defaults and surfaces a notice in the footer.

API Client

Need to build your own UI? Use the PapavlopClient directly:

import { PapavlopClient } from '@vlop/ai'

const client = new PapavlopClient('vlop_xxx')
const config = await client.getConfig() // Remote theme + prompt

await client.chat(
  [{ role: 'user', content: 'Suggest a cozy anime marathon.' }],
  { systemPrompt: config.systemPrompt },
  chunk => console.log(chunk)
)

Build

npm run build

Compiles ES modules and type declarations into dist/. Publish with npm publish --access public.

License

MIT (c) Vlop