chiipi-hello-ai

Gemini-powered personalized mascot greeting package for React apps using styled-components.

Features

• Displays a mascot with greeting bubble
• Uses Google Gemini (@google/genai) for AI-powered recommendations
• Custom messages: Set default greeting messages via defaultMessages prop
• Source context: Pass API data or other context with the source prop
• Recommendation modal: Click "Give me recommendation" to open modal with textarea
• Y-overflow scroll: Modal supports scrolling for long content
• Fallback mode: Without a Gemini API key, the recommendation button is hidden and default messages keep cycling
• Clickable links: Plain http/https URLs in default messages render as links
• Click mascot to toggle greeting bubble
• Close the mascot and bubble with the x icon next to the mascot
• Styled with styled-components
• Browser-ready builds (ESM, CJS, UMD)
• Default mascot images bundled from src/images/
• Next.js compatible with "use client" directive

Installation

npm install chiipi-hello-ai
# or
yarn add chiipi-hello-ai

Usage

Basic (Generic Greeting)

import { ChiipiMascot } from 'chiipi-hello-ai'

function App() {
  return (
    <ChiipiMascot
      apiKey="your-gemini-api-key"
    />
  )
}

Custom Default Messages

Set defaultMessages prop to show rotating welcome messages:

<ChiipiMascot
  apiKey="your-gemini-api-key"
  defaultMessages={['Hello!', 'Welcome!', 'Hi there!']}
/>

Default messages can include plain http/https URLs and they will be clickable.

Context Source

Pass API data or other context to shape the greeting/recommendation:

<ChiipiMascot
  apiKey="your-gemini-api-key"
  source={{
    userName: 'Ayu',
    plan: 'Pro',
    recentAction: 'Viewed pricing page'
  }}
/>

Recommendation Modal

Click "Give me recommendation" button in the bubble to open a modal with textarea:

• Type your question/prompt
• Press Ctrl+Enter (or click Submit) to call Gemini API
• Result appears in the bubble
• Modal has y-overflow scroll for long content

Customize placeholder text:

<ChiipiMascot
  apiKey="your-gemini-api-key"
  placeholderText="What do you need help with?"
/>

Prompt Evaluation

Use evaluatePrompt to score a prompt and return structured JSON:

import { evaluatePrompt } from 'chiipi-hello-ai'

const result = await evaluatePrompt('Review this text', 'en')
// { score, feedback, tips }

Custom Mascot Images

Pass an array of image URLs/paths. Defaults to bundled images from src/images/:

import { Chiip'iMascot } from 'chiip'i-hello-ai'

function App() {
  return (
    <Chiip'iMascot
      apiKey="your-gemini-api-key"
      mascotSrc={['/mascot1.png', '/mascot2.png', '/mascot3.png']}
    />
  )
}

Positioning

Use x and y props for flexible positioning:

<ChiipiMascot
  apiKey="your-gemini-api-key"
  x="left"     // 'left' | 'center' | 'right'
  y="top"      // 'top' | 'center' | 'bottom'
/>

How It Works

1. Mascot renders at the specified position with a random image from mascotSrc array
2. On mount → Shows default message (from defaultMessages prop)
3. Click "Give me recommendation" → Opens modal with textarea → Submit calls Gemini API → shows result in bubble
4. Click mascot → toggles bubble visibility (no API call on click)
5. Click the x icon → hides both the mascot and the bubble

If no Gemini API key is provided, the recommendation button stays hidden and the default greeting messages continue cycling.

Testing with npm link

Prerequisites

• Node.js installed
• A Gemini API key (optional, for personalized greetings)

Steps

1. Build the library:

   cd /Users/oktaviardi/Okta/opencode/chiipi-hello-ai
   npm run build
   npm link

2. Create a Next.js app:

   npx create-next-app@latest chiipi-test --app --no-turbopack
   cd chiipi-test && npm install

3. Link the local package:

   npm link chiipi-hello-ai

4. Install required peer dependencies:

   npm install styled-components @google/genai

5. Add the component to src/app/page.jsx:

   'use client'
   
   import { Chiip'iMascot } from 'chiip'i-hello-ai'
   
   export default function Home() {
     return (
       <main>
         <Chiip'iMascot
           apiKey="your-gemini-api-key"
           x="right"
           y="bottom"
         />
       </main>
     )
   }

6. Run the test app:

   npm run dev

7. Verify:

   • Open the local URL (usually http://localhost:3000)
   • Default message shown on mount
   • Click mascot to show/hide bubble
   • Click the x icon to hide the mascot and bubble
   • Click "Give me recommendation" → Type prompt → Submit → API called
   • Omit apiKey to test generic fallback greetings

Props

You can pass props to customize the mascot and bubble. Example signature with defaults:

apiKey,
mascotSrc = defaultMascotImages,
defaultMessages = ['Hello, welcome to our site!'],
source,
context = {},
placeholderText = 'What is your favorite thing?',
x = 'right',
y = 'bottom',
model = 'gemini-3.1-pro-preview',
autoPlay = true,
shuffleIntervalMs = 15000

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | - | Gemini API key (or set VITE_GEMINI_API_KEY env var). If not provided the recommendation button is hidden and fallback messages are used. | | mascotSrc | string[] | bundled images | Array of mascot image URLs/paths. A random image is selected on mount. | | defaultMessages | string[] | ['Hello, welcome to our site!'] | Default greeting messages. Shuffled on mount and used for rotation/cycling when autoPlay is enabled. | | source | any | - | Context data passed into Gemini prompts (API data, user data, etc.). Can be an object or string. | | context | object | {} | Alias/extra context used when source is not provided. | | placeholderText | string | 'What is your favorite thing?' | Placeholder text for the recommendation modal textarea. | | x | 'left'  'center'  'right' | right | Horizontal position of mascot/bubble. | | y | 'top'  'center'  'bottom' | bottom | Vertical position of mascot/bubble. | | model | string | gemini-3.1-pro-preview | Gemini model to use for recommendations/evaluations. | | autoPlay | boolean | true | When true and no apiKey is present, default messages auto-rotate. When false rotation is disabled. | | shuffleIntervalMs | number | 15000 | Interval in milliseconds between message rotations when autoPlay is enabled. |

Notes:

• The component shuffles defaultMessages on mount (or when the prop changes) using Fisher–Yates and then cycles through them when autoPlay is true and no Gemini key is present.
• Use apiKey (or VITE_GEMINI_API_KEY) to enable Gemini-powered recommendations. When enabled, the Recommend button is shown and the chat/session flow is used to persist context.
• source is truncated before sending to the API to reduce payload size when needed. If you pass large objects, consider pre-filtering unnecessary fields.

Environment Variables

Set VITE_GEMINI_API_KEY in your Vite project to avoid passing apiKey prop.

Build

npm run build

Next.js Usage

This package includes "use client" directive for Next.js compatibility. Import directly in your Client Components:

'use client'

import { ChiipiMascot } from 'chiipi-hello-ai'

export default function Home() {
  return (
    <main>
      <ChiipiMascot
        apiKey="your-gemini-api-key"
        x="right"
        y="bottom"
      />
    </main>
  )
}

Note: API is called when user submits the recommendation modal. Default messages are shown on mount.