@metricshift/react 1.2.0 → 1.4.0

package/README.md

@@ -1,47 +1,57 @@
-# @metricshift/react
+@metricshift/react
 
-The intelligent feedback SDK for React applications. Collect, store, and analyze user feedback with built-in AI insights — in minutes, not weeks.
+The intelligent feedback widget for React applications.
+Collect, analyze, and act on user feedback with AI-powered insights — in minutes, not weeks.
 
-[![npm version](https://img.shields.io/npm/v/@metricshift/react.svg)](https://www.npmjs.com/package/@metricshift/react)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+MetricShift gives you a drop-in feedback experience that feels native to your product, while quietly powering a structured analytics pipeline behind the scenes.
 
-## ✨ Features
+You can fully customize the widget — including rich media like avatars and images — so it feels truly brand-specific, not like a generic feedback tool.
 
-- 🚀 **2-Minute Setup** - Add powerful feedback collection to your React app instantly
-- 🎨 **Fully Customizable** - Match your brand with custom colors, sizes, and styles
-- 🤖 **AI-Powered Insights** - Automatic sentiment analysis and theme detection with GPT-4
-- 📊 **Beautiful Dashboard** - View trends, export data, and discover insights
-- ♿ **Accessible** - WCAG compliant with keyboard navigation and ARIA labels
-- 📱 **Mobile-Ready** - Perfect experience on any device
-- 🔒 **Privacy-First** - GDPR compliant, you control your data
-- 🎯 **TypeScript** - Full type safety included
 
-## 📦 Installation
-```bash
+
+
+✨ Features
+
+🚀 2-Minute Setup — Drop-in widget with modal + backend wired automatically
+
+🎨 Deep Customization — Colors, variants, avatars, images, inline placement
+
+🖼️ Rich Media Support — Add personal avatars or branded visuals to the widget
+
+🤖 AI-Powered Analysis — Sentiment detection, themes, summaries
+
+📊 Analytics-Ready — Widget events can be streamed into your analytics stack
+
+🔒 Safe by Design — Domain restrictions + rate limiting built in
+
+♿ Accessible — WCAG-friendly, keyboard & screen-reader support
+
+📱 Mobile-First — Works beautifully on all screen sizes
+
+🧩 TypeScript Ready — Full types & IntelliSense
+
+📦 Installation
 npm install @metricshift/react
-```
+
 
 or
-```bash
-yarn add @metricshift/react
-```
 
-## 🚀 Quick Start
+yarn add @metricshift/react
 
-### 1. Sign up for MetricShift
+🚀 Quick Start
+1. Create a MetricShift project
 
-Create your free account at [metricshift.co](https://metricshift.co) to get your credentials.
+Get your Project ID and API key from
+👉 https://metricshift.co
 
-### 2. Add the Feedback Button
-```tsx
+2. Add the feedback widget
 import { FeedbackButton } from '@metricshift/react';
 
 function App() {
   return (
     <div>
-      <h1>My Awesome App</h1>
-      
-      {/* Feedback button in bottom-right corner */}
+      <h1>My App</h1>
+
       <FeedbackButton
         projectId="your-project-id"
         apiKey="your-api-key"
@@ -49,275 +59,249 @@ function App() {
     </div>
   );
 }
-```
 
-### 3. View Feedback & Insights
+3. View feedback & AI insights
 
-Log in to your [MetricShift dashboard] to:
-- View all feedback in real-time
-- See AI-generated sentiment analysis
-- Discover common themes automatically
-- Export data to CSV
-- Track trends over time
+Open your MetricShift dashboard to explore:
 
-That's it! 🎉
+Real-time feedback
 
-## 📚 Usage Examples
+AI sentiment & themes
 
-### Default Floating Button
-```tsx
-<FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
-/>
-```
+Filters, exports, trends
+
+Project-level analytics
+
+That’s it 🎉
 
-Perfect for most apps - floats in the bottom-right corner.
+🧠 Security note (important)
 
-### Custom Styled Button
-```tsx
+It is safe to use projectId and apiKey in the frontend.
+
+MetricShift protects your widget with:
+
+Domain allow-listing (fully configurable in the dashboard)
+
+Rate limiting to prevent abuse or hijacking
+
+Project-scoped keys (no cross-project access)
+
+If you prefer, you can still proxy keys via your backend — but for most use cases, frontend usage is perfectly fine.
+
+📚 Usage Examples
+⭐ Default Floating Button
 <FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
-  buttonText="Share Feedback"
-  buttonColor="#10b981"
-  buttonHoverColor="#059669"
-  size="large"
-  position="bottom-left"
+  projectId={projectId}
+  apiKey={apiKey}
 />
-```
 
-Match your brand colors and position.
 
-### Inline Button
-```tsx
+Clean, neutral pill — bottom-right by default.
+
+🖼️ Custom Styled Button with Image / Avatar
+
+Use rich media to make the widget feel personal and brand-specific.
+
 <FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
+  projectId={projectId}
+  apiKey={apiKey}
+  apiUrl={apiUrl}
   position="inline"
-  buttonText="Help us improve"
-  showIcon={false}
+
+  buttonText="Image"
+  subtitleText="And subtitle"
+
+  buttonTextColor="#000000"
+
+  avatarSrc="/niklasAvatar.png"
+  avatarAlt="MetricShift Support"
+  avatarSize={44}
 />
-```
 
-Perfect for embedding in your UI, forms, or settings pages.
 
-### With Event Callbacks
-```tsx
+Perfect for:
+
+Founder-led products
+
+Customer success flows
+
+Onboarding & support touchpoints
+
+🎨 Brand-Themed Button
 <FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
-  onSuccess={(feedbackId) => {
-    // Track in your analytics
-    analytics.track('Feedback Submitted', { feedbackId });
-    // Show thank you message
-    toast.success('Thanks for your feedback!');
-  }}
-  onError={(error) => {
-    // Handle errors gracefully
-    console.error('Feedback error:', error);
-  }}
+  projectId={projectId}
+  apiKey={apiKey}
+  variant="solid"
+  accentColor="#3b82f6"
+  buttonText="Share feedback"
+  size="large"
 />
-```
 
-Integrate with your existing analytics and notification systems.
 
-### Multiple Feedback Buttons
-```tsx
-function App() {
-  return (
-    <div>
-      {/* Bug report button in header */}
-      <header>
-        <FeedbackButton
-          projectId="your-project-id"
-          apiKey="your-api-key"
-          position="inline"
-          buttonText="Report Bug"
-          buttonColor="#ef4444"
-          size="small"
-        />
-      </header>
-      
-      {/* General feedback floating button */}
-      <FeedbackButton
-        projectId="your-project-id"
-        apiKey="your-api-key"
-        position="bottom-right"
-      />
-    </div>
-  );
-}
-```
+Variants:
 
-## 🎛️ Props Reference
+solid — strong CTA
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `projectId` | `string` | **required** | Your MetricShift project ID |
-| `apiKey` | `string` | **required** | Your MetricShift API key |
-| `apiUrl` | `string` | `'https://api.metricshift.co'` | API endpoint (rarely needs changing) |
-| `buttonText` | `string` | `'Feedback'` | Text displayed on the button |
-| `showIcon` | `boolean` | `true` | Show/hide the 💬 icon |
-| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'inline'` | `'bottom-right'` | Button position |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Button size |
-| `buttonColor` | `string` | `'#3b82f6'` | Button background color |
-| `buttonHoverColor` | `string` | `'#2563eb'` | Hover state color |
-| `buttonTextColor` | `string` | `'#ffffff'` | Text color |
-| `customStyles` | `CSSProperties` | `{}` | Additional CSS styles |
-| `customClassName` | `string` | `''` | Custom CSS class |
-| `disabled` | `boolean` | `false` | Disable the button |
-| `autoOpen` | `boolean` | `false` | Auto-open modal on mount |
-| `onOpen` | `() => void` | - | Callback when modal opens |
-| `onClose` | `() => void` | - | Callback when modal closes |
-| `onSuccess` | `(feedbackId: string) => void` | - | Callback on successful submission |
-| `onError` | `(error: Error) => void` | - | Callback on error |
+outline — default
 
-## 🎨 Styling Examples
+ghost — minimal
 
-### Match Your Brand
-```tsx
+🧬 Inline Button (Embed Anywhere)
 <FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
-  buttonColor="#FF6B6B"  // Your primary color
-  buttonHoverColor="#EE5A52"  // Slightly darker
-  buttonTextColor="#FFFFFF"
-  customStyles={{
-    fontFamily: 'YourCustomFont, sans-serif',
-    borderRadius: '12px',
-    boxShadow: '0 4px 12px rgba(255, 107, 107, 0.3)'
-  }}
+  projectId={projectId}
+  apiKey={apiKey}
+  position="inline"
+  buttonText="Help us improve"
 />
-```
 
-### Minimal Style
-```tsx
+
+Ideal for settings pages, dashboards, forms.
+
+🔧 Event Callbacks & Analytics
+
+Callbacks let you connect widget events to your own analytics or product logic.
+
+Think:
+
+Tracking feedback submissions in GA / Segment / PostHog
+
+Triggering in-app messages
+
+Logging events internally
+
 <FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
-  showIcon={false}
-  buttonColor="transparent"
-  buttonHoverColor="#f3f4f6"
-  buttonTextColor="#111827"
-  customStyles={{
-    border: '1px solid #e5e7eb',
-    fontWeight: '400'
-  }}
+  projectId={projectId}
+  apiKey={apiKey}
+  onOpen={() => analytics.track('feedback_opened')}
+  onSuccess={(id) => analytics.track('feedback_submitted', { id })}
+  onError={(err) => console.error(err)}
 />
-```
 
-### Pill Shape
-```tsx
+
+This turns the widget into a first-class analytics signal, not just a UI element.
+
+🔧 Why callbacks matter
+
+MetricShift callbacks turn the feedback widget into a first-class analytics signal — not just a UI element.
+
+Every meaningful interaction inside the widget can be connected to your existing tools and workflows.
+
+Think of callbacks as hooks into user intent.
+
+Common use cases
+
+Track feedback opens & submissions in GA, Segment, PostHog, etc.
+
+Correlate feedback with feature usage or experiments
+
+Trigger UX responses (toasts, modals, follow-ups)
+
+Log feedback IDs for later investigation or support workflows
+
+Example
 <FeedbackButton
-  projectId="your-project-id"
-  apiKey="your-api-key"
-  customStyles={{
-    borderRadius: '999px',
-    padding: '12px 24px'
-  }}
+  projectId={projectId}
+  apiKey={apiKey}
+  onOpen={() => analytics.track('feedback_opened')}
+  onClose={() => analytics.track('feedback_closed')}
+  onSuccess={(id) =>
+    analytics.track('feedback_submitted', { feedbackId: id })
+  }
+  onError={(err) =>
+    analytics.track('feedback_error', { message: err.message })
+  }
 />
-```
 
-## 📊 Dashboard Features
 
-Your MetricShift dashboard includes:
+Instead of treating feedback as something you “look at later”, callbacks let you:
 
-- **Real-time Feedback Stream** - See submissions as they happen
-- **AI Sentiment Analysis** - Automatic positive/neutral/negative classification
-- **Theme Detection** - GPT-4 identifies common topics and patterns
-- **Advanced Filters** - Filter by type, sentiment, date, rating
-- **Export to CSV** - Download your data anytime
-- **Analytics & Trends** - Visualize feedback over time
-- **Search** - Find specific feedback instantly
+Act on feedback at the moment intent happens.
 
-[View Dashboard →](https://metricshift.co/dashboard)
+## 🧩 Props
 
-## 💼 Pricing
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `projectId` | `string` | **required** | MetricShift project ID |
+| `apiKey` | `string` | **required** | Project API key |
+| `apiUrl` | `string` | `https://metricshift-sdk-be-production.up.railway.app` | MetricShift API backend endpoint |
+| `buttonText` | `string` | `Feedback` | Main label |
+| `subtitleText` | `string` | `undefined` | Optional second line |
+| `avatarSrc` | `string` | `undefined` | Avatar / image URL |
+| `avatarAlt` | `string` | `''` | Accessible alt text |
+| `avatarSize` | `number` | `40` | Avatar diameter (px) |
+| `variant` | `'solid' \| 'outline' \| 'ghost'` | `'outline'` | Visual style |
+| `accentColor` | `string` | `'#111827'` | Brand accent color |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'inline'` | `'bottom-right'` | Widget placement |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Button size |
+| `customStyles` | `CSSProperties` | `{}` | Inline style overrides |
+| `customClassName` | `string` | `''` | Custom CSS class |
+| `onOpen` | `() => void` | — | Fired when modal opens |
+| `onClose` | `() => void` | — | Fired when modal closes |
+| `onSuccess` | `(id: string) => void` | — | Fired on successful submission |
+| `onError` | `(error: Error) => void` | — | Fired on submission error |
 
-- **Free** - 100 feedback submissions/month
-- **Pro** - Starting at €19/month for growing teams
-- **Enterprise** - Custom solutions, self-hosted options available
+📊 Dashboard
 
-[View pricing →](https://metricshift.co/pricing)
+Your MetricShift dashboard includes:
 
-## 🔧 TypeScript Support
+Real-time feedback stream
 
-Full TypeScript definitions included! Get autocomplete and type safety:
-```tsx
-import { FeedbackButton, FeedbackButtonProps } from '@metricshift/react';
+AI sentiment & theme clustering
 
-const props: FeedbackButtonProps = {
-  projectId: 'abc123',
-  apiKey: 'xyz789',
-  onSuccess: (id: string) => console.log(id)
-};
+Search, filters & CSV export
 
-<FeedbackButton {...props} />
-```
+Project-level configuration
 
-## 🌍 Framework Support
+Domain restrictions & rate limits
 
-Works with any React framework:
+👉 https://metricshift.co
 
-- ✅ **Create React App**
-- ✅ **Next.js** (App Router & Pages Router)
-- ✅ **Vite**
-- ✅ **Remix**
-- ✅ **Gatsby**
+💼 Pricing
 
-## ❓ FAQ
+Free
 
-### Can I customize the feedback form?
+MetricShift starts free.
+For full plan details, limits, and AI token allowances, see:
 
-The form fields are standardized to ensure quality data collection and AI analysis. However, you can customize:
-- Button appearance and position
-- Colors and styling
-- Form behavior via callbacks
+👉 https://metricshift.co
 
-### Where is my data stored?
+❓ FAQ
+Can I customize the feedback form?
 
-Data is securely stored on MetricShift's cloud infrastructure with regular backups. Enterprise customers can request self-hosted deployments.
+Yes.
+The free plan includes a powerful “jack-of-all-trades” feedback template that works across most product use cases.
 
-### Is this GDPR compliant?
+We also support fully tailor-made templates that can be integrated directly into the widget. More templates and use-case-specific flows will be added as the platform evolves.
 
-Yes! MetricShift is GDPR compliant. Email collection is optional, and users can request data deletion at any time.
+Can I use this with multiple projects or websites?
 
-### Can I use this with multiple projects?
+Yes, absolutely.
 
-Yes! Each project gets its own `projectId` and `apiKey`. Install the SDK in each project and use different credentials.
+You can self-manage which domains and websites the widget runs on directly from the dashboard.
 
-### What's included in the free tier?
+What’s included in the free tier?
 
-- 100 feedback submissions per month
-- AI sentiment analysis
-- Theme detection
-- Full dashboard access
-- CSV export
+The free plan includes:
 
-## 🤝 Support & Resources
+Feedback collection
 
-- 📧 **Email**: niklas@iamfrontend.com
-- 📖 **Documentation**: [docs.metricshift.co](https://metricshift.co/docs)
-- 🐛 **Issues**: Report bugs via email
-- 🌐 **Website**: [metricshift.co](https://metricshift.co)
+Dashboard access
 
-## 🚀 What's Next?
+AI-powered analysis
 
-After installing the SDK:
+A generous monthly allowance of AI tokens to analyze your data
 
-1. **Customize the button** to match your brand
-2. **Test it out** by submitting feedback
-3. **Explore your dashboard** to see AI insights
-4. **Set up notifications** to get alerts for new feedback
-5. **Export data** and integrate with your workflow
+For up-to-date details, see:
+👉 https://metricshift.co
 
-## 📝 License
+📖 Documentation
 
-MIT © [MetricShift](https://metricshift.co)
+All documentation and updates live at:
+👉 https://metricshift.co
 
----
+📝 License
 
-**Built with ❤️ for product teams who care about their users**
+MIT © MetricShift
 
-[Get Started Free](https://metricshift.co/signup) 
+Built with ❤️ for teams who care about their users.
+Start free → https://metricshift.co/

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,eAAO,MAAM,WAAW;IACtB;;;OAGG;mBACY,iBAAiB;IAWhC;;OAEG;;CAEJ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,eAAO,MAAM,WAAW;IACtB;;;OAGG;mBACY,iBAAiB;IAWhC;;OAEG;;CAEJ,CAAC"}