@tekibo/feedpulse-sdk 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,191 @@
+# @tekibo/feedpulse-sdk
+
+Developer-first embeddable behavior analytics and feedback SDK for Nuxt and React.
+
+- Tracks user interactions from elements tagged with `data-fp-id`
+- Sends event batches to your FeedPulse ingest endpoint
+- Includes ready-to-use feedback widgets for Nuxt and React
+
+## Install
+
+```bash
+pnpm add @tekibo/feedpulse-sdk
+```
+
+## What this SDK tracks
+
+The SDK automatically tracks:
+
+- `click`: when users click an element that has `data-fp-id`
+- `hover`: when users hover an element for more than 500ms
+- `scroll_into_view`: when tagged elements enter viewport
+- `feedback`: explicit rating/message submissions from widget or manual API
+
+Each event includes context such as session id, visitor id, page path, device, browser, OS, metadata, and timestamp.
+
+## Backend requirements
+
+Your backend must expose an ingest endpoint compatible with this payload:
+
+```json
+{
+  "events": [
+    {
+      "projectApiKey": "fp_live_xxx",
+      "elementId": "hero-cta",
+      "eventType": "click",
+      "sessionId": "session-1",
+      "visitorId": "visitor-1",
+      "page": "/",
+      "device": "desktop",
+      "metadata": {},
+      "timestamp": "2026-03-12T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+In the FeedPulse codebase, the default server endpoint is:
+
+- `POST /api/ingest`
+
+## Quick start (Nuxt)
+
+Import from `@tekibo/feedpulse-sdk/nuxt` and wrap your app:
+
+```vue
+<script setup lang="ts">
+import { FeedPulseProvider, FeedPulseWidget } from "@tekibo/feedpulse-sdk/nuxt";
+</script>
+
+<template>
+  <FeedPulseProvider api-key="fp_live_your_project_key">
+    <NuxtPage />
+    <FeedPulseWidget id="global-feedback" position="bottom-right" />
+  </FeedPulseProvider>
+</template>
+```
+
+Tag any interactive element with `data-fp-id`:
+
+```vue
+<template>
+  <UButton data-fp-id="hero-cta">
+    Start free trial
+  </UButton>
+</template>
+```
+
+Use the composable for manual feedback/event calls:
+
+```vue
+<script setup lang="ts">
+import { useFeedPulse } from "@tekibo/feedpulse-sdk/nuxt";
+
+const tracker = useFeedPulse();
+
+function sendNps() {
+  tracker?.trackFeedback("nps-card", 5, "Great onboarding flow");
+}
+</script>
+```
+
+## Quick start (React)
+
+Import from `@tekibo/feedpulse-sdk/react`:
+
+```tsx
+import { FeedPulseProvider, FeedPulseWidget, useFeedPulse } from "@tekibo/feedpulse-sdk/react";
+
+function SaveButton() {
+  const { tracker } = useFeedPulse();
+
+  return (
+    <button
+      data-fp-id="settings-save"
+      onClick={() => tracker?.trackFeedback("settings-save", 5, "Saved successfully")}
+    >
+      Save
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <FeedPulseProvider apiKey="fp_live_your_project_key">
+      <button data-fp-id="hero-cta">Get Started</button>
+      <SaveButton />
+      <FeedPulseWidget id="global-feedback" position="bottom-right" />
+    </FeedPulseProvider>
+  );
+}
+```
+
+## Core API
+
+Import from `@tekibo/feedpulse-sdk`:
+
+```ts
+import { FeedPulseTracker } from "@tekibo/feedpulse-sdk";
+```
+
+`FeedPulseTracker` configuration:
+
+- `apiKey: string` required
+- `endpoint?: string` optional, defaults to `https://feedpulse.dev/api/ingest`
+- `batchInterval?: number` optional, defaults to `5000` ms
+
+Key methods:
+
+- `init()` start listeners and batching
+- `track(eventType, elementId, metadata?)` enqueue an event
+- `trackFeedback(elementId, rating, message)` send feedback immediately
+- `destroy()` stop listeners and flush queue
+
+## Widget props
+
+Nuxt and React widgets support:
+
+- `id?: string` element id used in feedback event
+- `placeholder?: string` prompt text
+- `position?: "bottom-right" | "bottom-left" | "inline"` default is `"bottom-right"`
+
+## Endpoint override
+
+Use this when sending to staging/self-hosted backend:
+
+### Nuxt
+
+```vue
+<FeedPulseProvider
+  api-key="fp_live_your_project_key"
+  endpoint="https://staging.your-domain.com/api/ingest"
+>
+  <NuxtPage />
+</FeedPulseProvider>
+```
+
+### React
+
+```tsx
+<FeedPulseProvider
+  apiKey="fp_live_your_project_key"
+  endpoint="https://staging.your-domain.com/api/ingest"
+>
+  {children}
+</FeedPulseProvider>
+```
+
+## Integration checklist for your app
+
+1. Create a project in FeedPulse dashboard and copy the project API key
+2. Install package and add provider at root layout/app level
+3. Add `data-fp-id` to primary buttons, links, forms, and sections
+4. Optionally mount `FeedPulseWidget` for direct user feedback
+5. Verify data appears in FeedPulse dashboard analytics and feedback pages
+
+## Package exports
+
+- `@tekibo/feedpulse-sdk` → core types + tracker
+- `@tekibo/feedpulse-sdk/nuxt` → `FeedPulseProvider`, `FeedPulseWidget`, `useFeedPulse`
+- `@tekibo/feedpulse-sdk/react` → `FeedPulseProvider`, `FeedPulseWidget`, `useFeedPulse`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekibo/feedpulse-sdk",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Embeddable analytics and feedback SDK for FeedPulse",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",