@feedvalue/core 0.1.0 → 0.1.2

package/README.md

@@ -35,8 +35,30 @@ feedvalue.open();
 feedvalue.close();
 ```
 
+### Headless Mode
+
+For complete UI control, initialize in headless mode. The SDK fetches config and provides all API methods but renders no DOM elements:
+
+```typescript
+const feedvalue = FeedValue.init({
+  widgetId: 'your-widget-id',
+  headless: true, // No trigger button or modal rendered
+});
+
+// Wait until ready
+await feedvalue.waitUntilReady();
+
+// Build your own UI, use SDK for submission
+await feedvalue.submit({
+  message: 'User feedback here',
+  sentiment: 'satisfied',
+});
+```
+
 ### User Identification
 
+User data is automatically included with feedback submissions:
+
 ```typescript
 // Identify the current user
 feedvalue.identify('user-123', {
@@ -61,14 +83,47 @@ feedvalue.reset();
 // Submit feedback programmatically
 await feedvalue.submit({
   message: 'Great product!',
-  sentiment: '😊',
+  sentiment: 'excited', // 'angry' | 'disappointed' | 'satisfied' | 'excited'
   metadata: {
     page_url: window.location.href,
-    custom_field: 'value',
   },
 });
 ```
 
+### Custom Fields
+
+Custom fields allow you to collect structured data beyond the main feedback message. **Custom fields must be defined in your widget configuration on the FeedValue dashboard before use.**
+
+1. Go to your widget settings in the FeedValue dashboard
+2. Add custom fields with types: `text`, `email`, or `emoji`
+3. Use `customFieldValues` to submit responses:
+
+```typescript
+await feedvalue.submit({
+  message: 'Detailed feedback',
+  customFieldValues: {
+    // Field IDs must match those defined in your widget configuration
+    name: 'John Doe',
+    category: 'feature',
+  },
+});
+```
+
+> **Important**: The field IDs in `customFieldValues` must match the field IDs defined in your widget configuration on the dashboard.
+
+### Waiting for Ready State
+
+```typescript
+// Wait until widget is fully initialized
+await feedvalue.waitUntilReady();
+console.log('Widget ready, config loaded');
+
+// Or use the event
+feedvalue.on('ready', () => {
+  console.log('Widget is ready');
+});
+```
+
 ### Event Handling
 
 ```typescript
@@ -93,6 +148,11 @@ feedvalue.on('error', (error) => {
   console.error('Widget error:', error);
 });
 
+// Subscribe to a single event emission
+feedvalue.once('ready', () => {
+  console.log('First ready event only');
+});
+
 // Unsubscribe from events
 feedvalue.off('open', handleOpen);
 ```
@@ -111,17 +171,32 @@ const state = feedvalue.getSnapshot();
 // { isReady, isOpen, isVisible, error, isSubmitting }
 ```
 
+### Configuration Updates
+
+```typescript
+// Update runtime configuration
+feedvalue.setConfig({
+  theme: 'dark',
+  debug: true,
+});
+
+// Get current configuration
+const config = feedvalue.getConfig();
+```
+
 ## API Reference
 
 ### `FeedValue.init(options)`
 
 Initialize a FeedValue instance.
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `widgetId` | `string` | Yes | Widget ID from FeedValue dashboard |
-| `apiBaseUrl` | `string` | No | Custom API URL (for self-hosted) |
-| `config` | `Partial<FeedValueConfig>` | No | Configuration overrides |
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `widgetId` | `string` | Yes | - | Widget ID from FeedValue dashboard |
+| `apiBaseUrl` | `string` | No | Production URL | Custom API URL (for self-hosted) |
+| `config` | `Partial<FeedValueConfig>` | No | - | Configuration overrides |
+| `headless` | `boolean` | No | `false` | Disable all DOM rendering |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
 
 ### Instance Methods
 
@@ -132,23 +207,41 @@ Initialize a FeedValue instance.
 | `toggle()` | Toggle the modal open/closed |
 | `show()` | Show the trigger button |
 | `hide()` | Hide the trigger button |
+| `isOpen()` | Check if modal is open |
+| `isVisible()` | Check if trigger is visible |
+| `isReady()` | Check if widget is ready |
+| `isHeadless()` | Check if running in headless mode |
 | `submit(feedback)` | Submit feedback programmatically |
 | `identify(userId, traits?)` | Identify the current user |
 | `setData(data)` | Set additional user data |
 | `reset()` | Reset user data |
 | `on(event, handler)` | Subscribe to events |
+| `once(event, handler)` | Subscribe to single event |
 | `off(event, handler?)` | Unsubscribe from events |
+| `waitUntilReady()` | Promise that resolves when ready |
 | `subscribe(callback)` | Subscribe to state changes |
 | `getSnapshot()` | Get current state |
+| `setConfig(config)` | Update runtime configuration |
 | `getConfig()` | Get current configuration |
 | `destroy()` | Destroy the widget instance |
 
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `ready` | - | Widget initialized, config loaded |
+| `open` | - | Modal opened |
+| `close` | - | Modal closed |
+| `submit` | `FeedbackData` | Feedback submitted successfully |
+| `error` | `Error` | An error occurred |
+| `stateChange` | `FeedValueState` | Any state change |
+
 ## Framework Packages
 
-For framework-specific integrations:
+For framework-specific integrations with hooks and components:
 
-- **React**: [@feedvalue/react](https://www.npmjs.com/package/@feedvalue/react)
-- **Vue**: [@feedvalue/vue](https://www.npmjs.com/package/@feedvalue/vue)
+- **React/Next.js**: [@feedvalue/react](https://www.npmjs.com/package/@feedvalue/react)
+- **Vue/Nuxt**: [@feedvalue/vue](https://www.npmjs.com/package/@feedvalue/vue)
 
 ## License
 

package/dist/index.cjs

@@ -140,14 +140,21 @@ var ApiClient = class {
   /**
    * Fetch widget configuration
    * Uses caching and request deduplication
+   *
+   * @param widgetId - Widget ID to fetch config for
+   * @param forceRefresh - Skip cache and fetch fresh config (used for token refresh)
    */
-  async fetchConfig(widgetId) {
+  async fetchConfig(widgetId, forceRefresh = false) {
     this.validateWidgetId(widgetId);
     const cacheKey = `config:${widgetId}`;
-    const cached = this.configCache.get(cacheKey);
-    if (cached && Date.now() < cached.expiresAt) {
-      this.log("Config cache hit", { widgetId });
-      return cached.data;
+    if (!forceRefresh) {
+      const cached = this.configCache.get(cacheKey);
+      if (cached && Date.now() < cached.expiresAt) {
+        this.log("Config cache hit", { widgetId });
+        return cached.data;
+      }
+    } else {
+      this.log("Bypassing cache for token refresh", { widgetId });
     }
     const pendingKey = `fetchConfig:${widgetId}`;
     const pending = this.pendingRequests.get(pendingKey);
@@ -173,7 +180,12 @@ var ApiClient = class {
     if (this.fingerprint) {
       headers["X-Client-Fingerprint"] = this.fingerprint;
     }
-    this.log("Fetching config", { widgetId, url });
+    this.log("Fetching config", {
+      widgetId,
+      url,
+      hasFingerprint: !!this.fingerprint,
+      fingerprintPreview: this.fingerprint ? `${this.fingerprint.substring(0, 8)}...` : null
+    });
     const response = await fetch(url, {
       method: "GET",
       headers
@@ -189,6 +201,12 @@ var ApiClient = class {
       this.log("Submission token stored", {
         expiresAt: this.tokenExpiresAt ? new Date(this.tokenExpiresAt * 1e3).toISOString() : "unknown"
       });
+    } else {
+      this.log("No submission token in response", {
+        hasWidgetId: !!data.widget_id,
+        hasConfig: !!data.config,
+        responseKeys: Object.keys(data)
+      });
     }
     const cacheKey = `config:${widgetId}`;
     this.configCache.set(cacheKey, {
@@ -206,7 +224,7 @@ var ApiClient = class {
     const url = `${this.baseUrl}/api/v1/widgets/${widgetId}/feedback`;
     if (!this.hasValidToken()) {
       this.log("Token expired, refreshing...");
-      await this.fetchConfig(widgetId);
+      await this.fetchConfig(widgetId, true);
     }
     if (!this.submissionToken) {
       throw new Error("No submission token available");
@@ -219,17 +237,20 @@ var ApiClient = class {
       headers["X-Client-Fingerprint"] = this.fingerprint;
     }
     this.log("Submitting feedback", { widgetId });
+    const mergedMetadata = {
+      ...feedback.metadata,
+      ...userData && Object.keys(userData).length > 0 && {
+        user: userData
+      }
+    };
     const response = await fetch(url, {
       method: "POST",
       headers,
       body: JSON.stringify({
         message: feedback.message,
-        metadata: feedback.metadata,
+        metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : void 0,
         ...feedback.customFieldValues && {
           customFieldValues: feedback.customFieldValues
-        },
-        ...userData && Object.keys(userData).length > 0 && {
-          user: userData
         }
       })
     });
@@ -247,7 +268,7 @@ var ApiClient = class {
       if (errorMessage.includes("token") || errorMessage.includes("expired")) {
         this.log("Token rejected, refreshing...");
         this.submissionToken = null;
-        await this.fetchConfig(widgetId);
+        await this.fetchConfig(widgetId, true);
         if (this.submissionToken) {
           headers["X-Submission-Token"] = this.submissionToken;
           const retryResponse = await fetch(url, {
@@ -314,33 +335,33 @@ var ApiClient = class {
 
 // src/fingerprint.ts
 var FINGERPRINT_STORAGE_KEY = "fv_fingerprint";
-function generateUUID() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
-  }
-  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
-    const bytes = new Uint8Array(16);
-    crypto.getRandomValues(bytes);
-    bytes[6] = bytes[6] & 15 | 64;
-    bytes[8] = bytes[8] & 63 | 128;
-    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-  }
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = Math.random() * 16 | 0;
-    const v = c === "x" ? r : r & 3 | 8;
-    return v.toString(16);
-  });
+function generateHexFingerprint() {
+  if (typeof crypto === "undefined" || typeof crypto.getRandomValues !== "function") {
+    throw new Error(
+      "crypto.getRandomValues is required but not available. Ensure you are running in a modern browser or Node.js 15+."
+    );
+  }
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function generateFingerprint() {
   if (typeof window === "undefined" || typeof sessionStorage === "undefined") {
-    return generateUUID();
+    return generateHexFingerprint();
   }
   const stored = sessionStorage.getItem(FINGERPRINT_STORAGE_KEY);
   if (stored) {
+    if (stored.includes("-")) {
+      const hexFingerprint = stored.replace(/-/g, "");
+      try {
+        sessionStorage.setItem(FINGERPRINT_STORAGE_KEY, hexFingerprint);
+      } catch {
+      }
+      return hexFingerprint;
+    }
     return stored;
   }
-  const fingerprint = generateUUID();
+  const fingerprint = generateHexFingerprint();
   try {
     sessionStorage.setItem(FINGERPRINT_STORAGE_KEY, fingerprint);
   } catch {