@product7/product7-js 0.3.2 → 0.3.4

package/src/docs/installation.md

@@ -2,7 +2,7 @@
 
 ## Package Installation
 
-### NPM
+### npm
 
 ```bash
 npm install @product7/product7-js
@@ -17,34 +17,50 @@ yarn add @product7/product7-js
 ### CDN
 
 ```html
-<script src="https://cdn.product7.io/product7-js/latest/product7-js.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@product7/product7-js@latest/dist/product7-js.min.js"></script>
 ```
 
 ---
 
 ## Quick Setup
 
-### 1. Import and Initialize
+### 1. Create the SDK
 
 ```javascript
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
 const sdk = new Product7({
 	workspace: 'your-workspace',
-	metadata: {
-		user_id: 'user_123',
-		email: 'user@example.com',
-		name: 'John Doe',
-	},
+	boardName: 'feature-requests',
 });
+```
 
+### 2. Initialize the session
+
+```javascript
 await sdk.init();
 ```
 
-### 2. Create Widget
+### 3. Identify the current user
 
 ```javascript
-const widget = sdk.createWidget('button');
+await sdk.identify({
+	user_id: 'user_123',
+	email: 'user@example.com',
+	name: 'John Doe',
+	custom_fields: {
+		plan: 'pro',
+		role: 'admin',
+	},
+});
+```
+
+### 4. Create and mount a widget
+
+```javascript
+const widget = sdk.createFeedbackWidget({
+	position: 'bottom-right',
+});
 widget.mount();
 ```
 
@@ -52,91 +68,117 @@ widget.mount();
 
 ## Installation Methods
 
-### Method 1: NPM/ES Modules
+### Method 1: npm / ESM
 
 ```javascript
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
 const sdk = new Product7({
-	/* config */
+	workspace: 'your-workspace',
+	boardName: 'feature-requests',
 });
+
 await sdk.init();
+await sdk.identify({
+	user_id: 'user_123',
+	email: 'user@example.com',
+});
 
-const widget = sdk.createWidget('button');
+const widget = sdk.createFeedbackWidget();
 widget.mount();
 ```
 
-### Method 2: CDN with Auto-Init
+### Method 2: CDN
 
 ```html
+<script src="https://cdn.jsdelivr.net/npm/@product7/product7-js@latest/dist/product7-js.min.js"></script>
 <script>
-	window.Product7Config = {
-		workspace: 'your-workspace',
-		metadata: {
+	async function bootProduct7() {
+		const sdk = new window.Product7.Product7SDK({
+			workspace: 'your-workspace',
+			boardName: 'feature-requests',
+		});
+
+		await sdk.init();
+		await sdk.identify({
 			user_id: 'user_123',
 			email: 'user@example.com',
-		},
-	};
-</script>
-<script src="https://cdn.product7.io/product7-js/latest/product7-js.js"></script>
-<script>
-	// SDK auto-initializes and is available at window.Product7
-	window.Product7.onReady((sdk) => {
-		const widget = sdk.createWidget('button');
+		});
+
+		const widget = sdk.createFeedbackWidget({
+			position: 'bottom-right',
+		});
 		widget.mount();
-	});
+	}
+
+	bootProduct7();
 </script>
 ```
 
-### Method 3: Manual CDN
+### Method 3: Headless Feedback
 
-```html
-<script src="https://cdn.product7.io/product7-js/latest/product7-js.js"></script>
-<script>
-	const sdk = new window.Product7({
-		workspace: 'your-workspace',
-		metadata: {
-			user_id: 'user_123',
-			email: 'user@example.com',
-		},
-	});
+Use `headless: true` when you want to control opening from your own UI instead of rendering the default floating trigger.
 
-	sdk.init().then(() => {
-		const widget = sdk.createWidget('button');
-		widget.mount();
-	});
-</script>
+```javascript
+const widget = sdk.createFeedbackWidget({
+	headless: true,
+	boardName: 'feature-requests',
+});
+
+widget.mount();
+
+document
+	.querySelector('#leave-feedback')
+	?.addEventListener('click', () => widget.open());
 ```
 
 ---
 
-## Framework Integration
+## Framework Examples
 
 ### React
 
 ```jsx
-import { useEffect, useState } from 'react';
-import Product7 from '@product7/product7-js';
+import { useEffect, useRef } from 'react';
+import { Product7 } from '@product7/product7-js';
 
 function App() {
-	const [sdk, setSdk] = useState(null);
+	const sdkRef = useRef(null);
+	const widgetRef = useRef(null);
 
 	useEffect(() => {
-		const product7 = new Product7({
-			workspace: 'your-workspace',
-			metadata: {
-				user_id: 'user_123',
-				email: 'user@example.com',
-			},
-		});
+		let disposed = false;
 
-		product7.init().then(() => {
-			setSdk(product7);
-			const widget = product7.createWidget('button');
-			widget.mount();
-		});
+		(async () => {
+			const sdk = new Product7({
+				workspace: 'your-workspace',
+				boardName: 'feature-requests',
+			});
 
-		return () => product7.destroy();
+			await sdk.init();
+			await sdk.identify({
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'John Doe',
+			});
+
+			if (disposed) {
+				sdk.destroy();
+				return;
+			}
+
+			sdkRef.current = sdk;
+			widgetRef.current = sdk.createFeedbackWidget({
+				position: 'bottom-right',
+			});
+			widgetRef.current.mount();
+		})();
+
+		return () => {
+			disposed = true;
+			widgetRef.current?.destroy();
+			sdkRef.current?.destroy();
+		};
 	}, []);
 
 	return <div>Your App</div>;
@@ -147,93 +189,64 @@ function App() {
 
 ```vue
 <script setup>
-	import { onMounted, onUnmounted } from 'vue';
-	import Product7 from '@product7/product7-js';
+	import { onMounted, onUnmounted, ref } from 'vue';
+	import { Product7 } from '@product7/product7-js';
 
-	let sdk = null;
+	const sdk = ref(null);
+	const widget = ref(null);
 
 	onMounted(async () => {
-		sdk = new Product7({
+		sdk.value = new Product7({
 			workspace: 'your-workspace',
-			metadata: {
-				user_id: 'user_123',
-				email: 'user@example.com',
-			},
+			boardName: 'feature-requests',
 		});
 
-		await sdk.init();
-		const widget = sdk.createWidget('button');
-		widget.mount();
+		await sdk.value.init();
+		await sdk.value.identify({
+			user_id: 'user_123',
+			email: 'user@example.com',
+			name: 'John Doe',
+		});
+
+		widget.value = sdk.value.createFeedbackWidget({
+			position: 'bottom-right',
+		});
+		widget.value.mount();
 	});
 
 	onUnmounted(() => {
-		if (sdk) sdk.destroy();
+		widget.value?.destroy();
+		sdk.value?.destroy();
 	});
 </script>
-
-<template>
-	<div>Your App</div>
-</template>
 ```
 
-### Next.js
-
-```javascript
-// app/layout.js or pages/_app.js
-'use client';
-
-import { useEffect } from 'react';
-import Product7 from '@product7/product7-js';
-
-export default function RootLayout({ children }) {
-	useEffect(() => {
-		const sdk = new Product7({
-			workspace: 'your-workspace',
-			metadata: {
-				user_id: 'user_123',
-				email: 'user@example.com',
-			},
-		});
-
-		sdk.init().then(() => {
-			const widget = sdk.createWidget('button');
-			widget.mount();
-		});
-
-		return () => sdk.destroy();
-	}, []);
-
-	return (
-		<html>
-			<body>{children}</body>
-		</html>
-	);
-}
-```
-
----
-
-## TypeScript Setup
-
-The SDK includes TypeScript definitions out of the box.
+### TypeScript
 
 ```typescript
-import Product7, { SDKConfig, ButtonWidget } from '@product7/product7-js';
+import {
+	Product7,
+	type FeedbackConfig,
+	type FeedbackWidget,
+} from '@product7/product7-js';
 
-const config: SDKConfig = {
+const config: FeedbackConfig = {
 	workspace: 'your-workspace',
-	metadata: {
-		user_id: 'user_123',
-		email: 'user@example.com',
-		name: 'John Doe',
-	},
+	boardName: 'feature-requests',
 	theme: 'light',
 };
 
 const sdk = new Product7(config);
 await sdk.init();
+await sdk.identify({
+	user_id: 'user_123',
+	email: 'user@example.com',
+	name: 'John Doe',
+});
 
-const widget: ButtonWidget = sdk.createWidget('button');
+const widget: FeedbackWidget = sdk.createFeedbackWidget({
+	headless: true,
+});
 widget.mount();
 ```
 
@@ -243,39 +256,54 @@ widget.mount();
 
 ### SDK not initializing
 
-Check you have both `workspace` and `metadata` configured:
+Check that `workspace` is set:
 
 ```javascript
 const sdk = new Product7({
-	workspace: 'your-workspace', // Required
-	metadata: {
-		// Required
-		user_id: 'user_123', // Required: user_id or email
-		email: 'user@example.com',
-	},
+	workspace: 'your-workspace',
+});
+```
+
+### Identify not working
+
+Call `identify()` after `init()` and pass at least `user_id` or `email`:
+
+```javascript
+await sdk.init();
+await sdk.identify({
+	user_id: 'user_123',
+	email: 'user@example.com',
 });
 ```
 
 ### Widget not showing
 
-Ensure you call both `init()` and `mount()`:
+Make sure you initialize first, then mount the widget:
+
+```javascript
+await sdk.init();
+const widget = sdk.createFeedbackWidget();
+widget.mount();
+```
+
+### Custom trigger does nothing
+
+If you use `headless: true`, you still need to call `mount()` before `open()`:
 
 ```javascript
-await sdk.init(); // Initialize first
-const widget = sdk.createWidget('button');
-widget.mount(); // Then mount
+const widget = sdk.createFeedbackWidget({ headless: true });
+widget.mount();
+widget.open();
 ```
 
-### CDN auto-init not working
+### CDN usage fails
 
-Check `window.Product7Config` is set before loading the script:
+Use `window.Product7.Product7SDK` for the class-based API:
 
 ```html
-<!-- Config MUST come before script tag -->
 <script>
-	window.Product7Config = {
-		/* config */
-	};
+	const sdk = new window.Product7.Product7SDK({
+		workspace: 'your-workspace',
+	});
 </script>
-<script src="https://cdn.product7.io/product7-js/latest/product7-js.js"></script>
 ```

package/src/index.js

@@ -98,9 +98,21 @@ function cleanUndefined(obj) {
 	return obj;
 }
 
+function hasIdentifyMetadata(metadata = {}) {
+	return Object.values(metadata).some((value) => value !== undefined);
+}
+
 // --- Ensure SDK is initialized (shared by widget inits) ---
 
 async function ensureSDK(options) {
+	if (
+		Product7._sdk &&
+		options.organization &&
+		Product7._sdk.config.workspace !== options.organization
+	) {
+		Product7.destroy();
+	}
+
 	if (Product7._sdk) return Product7._sdk;
 
 	if (options.organization) {
@@ -143,63 +155,58 @@ const Product7 = {
 	async identify(data = {}, callback) {
 		try {
 			const transformed = transformIdentifyData(data);
-			Product7._organization = transformed.workspace;
+			Product7._organization =
+				transformed.workspace || Product7._organization || null;
 
 			const config = cleanUndefined({
-				workspace: transformed.workspace,
-				metadata: transformed.metadata,
+				workspace: Product7._organization,
 				debug: transformed.debug,
 				mock: transformed.mock,
 				env: transformed.env,
 				apiUrl: transformed.apiUrl,
 			});
 
-			const sdk = new Product7SDK(config);
-			const initData = await sdk.init();
-
-			Product7._sdk = sdk;
-			Product7._identified = true;
-
-			// Sync custom attributes + segments via /widget/identify
-			if (transformed.metadata && sdk.apiService?.sessionToken) {
-				try {
-					const identifyPayload = {
-						user_id: transformed.metadata.user_id,
-						email: transformed.metadata.email,
-						name: transformed.metadata.name,
-						avatar: transformed.metadata.profile_picture,
-						attributes: transformed.metadata.custom_fields || {},
-					};
-					if (transformed.metadata.company) {
-						identifyPayload.company = transformed.metadata.company;
-					}
-					await sdk.apiService._makeRequest('/widget/identify', {
-						method: 'POST',
-						body: JSON.stringify(identifyPayload),
-						headers: {
-							'Content-Type': 'application/json',
-							Authorization: `Bearer ${sdk.apiService.sessionToken}`,
-						},
-					});
-				} catch (identifyErr) {
-					if (config.debug) {
-						console.warn('[Product7] Attribute sync failed:', identifyErr);
-					}
+			let sdk = Product7._sdk;
+			const requiresNewSDK =
+				!sdk || (config.workspace && sdk.config.workspace !== config.workspace);
+
+			if (requiresNewSDK) {
+				if (Product7._sdk) {
+					Product7.destroy();
+					Product7._organization = config.workspace || null;
 				}
+				sdk = new Product7SDK(config);
+				Product7._sdk = sdk;
 			}
 
+			const initData = sdk.initialized
+				? {
+						alreadyInitialized: true,
+						sessionToken: sdk.apiService?.sessionToken,
+					}
+				: await sdk.init();
+
+			const identifyData = hasIdentifyMetadata(transformed.metadata)
+				? await sdk.identify(transformed.metadata)
+				: null;
+			Product7._identified = Boolean(identifyData?.identified);
+
 			Product7._flushQueue();
 
 			if (typeof window !== 'undefined' && typeof CustomEvent !== 'undefined') {
 				window.dispatchEvent(
 					new CustomEvent('Product7Ready', {
-						detail: { sdk, config, initData },
+						detail: { sdk, config: sdk.config, initData, identifyData },
 					})
 				);
 			}
 
 			if (typeof callback === 'function') callback(null);
-			return initData;
+			return {
+				...initData,
+				identified: Product7._identified,
+				identify: identifyData,
+			};
 		} catch (error) {
 			console.error('[Product7] Identify failed:', error);
 
@@ -258,7 +265,7 @@ const Product7 = {
 		if (!options.placement) {
 			widgetOptions.autoShow = false;
 			widgetOptions.displayMode = 'modal';
-			widgetOptions._noTriggerButton = true;
+			widgetOptions.headless = true;
 		} else {
 			// Trigger button is always visible when placement is set
 			widgetOptions.suppressAfterSubmission = false;
@@ -266,7 +273,7 @@ const Product7 = {
 		}
 
 		try {
-			const widget = sdk.createWidget('button', widgetOptions);
+			const widget = sdk.createFeedbackWidget(widgetOptions);
 			widget.mount();
 
 			if (options.placement) {
@@ -305,13 +312,13 @@ const Product7 = {
 			if (options.setBoard) {
 				Product7._feedbackWidget.options.boardName = options.setBoard;
 			}
-			Product7._feedbackWidget.openPanel();
+			Product7._feedbackWidget.open();
 		}
 	},
 
 	closeFeedback() {
 		if (Product7._feedbackWidget) {
-			Product7._feedbackWidget.closePanel();
+			Product7._feedbackWidget.close();
 		}
 	},
 
@@ -370,7 +377,7 @@ const Product7 = {
 		widgetOptions.enabled = true;
 
 		try {
-			const widget = sdk.createWidget('messenger', widgetOptions);
+			const widget = sdk.createMessengerWidget(widgetOptions);
 			widget.mount();
 			widget.show();
 

package/src/widgets/MessengerWidget.js

@@ -100,6 +100,10 @@ export class MessengerWidget extends BaseWidget {
 		this._handleConversationClosed = this._handleConversationClosed.bind(this);
 	}
 
+	_hasTrigger() {
+		return this.options.trigger === true || this.options.trigger === undefined;
+	}
+
 	_createInternalFeedbackWidget() {
 		try {
 			const widget = this.sdk.createWidget('button', {
@@ -135,11 +139,13 @@ export class MessengerWidget extends BaseWidget {
 			this._feedbackWidget = this._createInternalFeedbackWidget();
 		}
 
-		this.launcher = new MessengerLauncher(this.messengerState, {
-			position: this.messengerOptions.position,
-			primaryColor: this.messengerOptions.primaryColor,
-		});
-		container.appendChild(this.launcher.render());
+		if (this._hasTrigger()) {
+			this.launcher = new MessengerLauncher(this.messengerState, {
+				position: this.messengerOptions.position,
+				primaryColor: this.messengerOptions.primaryColor,
+			});
+			container.appendChild(this.launcher.render());
+		}
 
 		this.panel = new MessengerPanel(this.messengerState, {
 			position: this.messengerOptions.position,
@@ -274,28 +280,13 @@ export class MessengerWidget extends BaseWidget {
 
 	async _handleIdentifyContact(contactData) {
 		try {
-			const response = await this.apiService.identifyContact({
-				name: contactData.name,
+			// Route through sdk.identify() so the SDK-level identity state is updated
+			// and applyIdentity() handles the messenger state + WebSocket as a side effect.
+			const result = await this.sdk.identify({
 				email: contactData.email,
+				name: contactData.name,
 			});
-
-			if (response.status) {
-				console.log(
-					'[MessengerWidget] Contact identified:',
-					response.data.contact_id
-				);
-				this.messengerState.setIdentified(true, {
-					name: contactData.name,
-					email: contactData.email,
-				});
-
-				// Start WebSocket now that session token is available
-				if (this.apiService?.sessionToken && !this.wsService?.isConnected) {
-					this._initWebSocket();
-				}
-			}
-
-			return response;
+			return result;
 		} catch (error) {
 			console.error('[MessengerWidget] Failed to identify contact:', error);
 			throw error;
@@ -303,10 +294,14 @@ export class MessengerWidget extends BaseWidget {
 	}
 
 	markAsIdentified(name, email) {
-		this.messengerState.setIdentified(true, { name, email });
-		console.log('[MessengerWidget] Marked as identified:', email);
+		// Called externally by the app when the user is already known.
+		// No API call needed — identity was already established via sdk.identify().
+		this.applyIdentity({ name, email });
+	}
+
+	applyIdentity(metadata = {}) {
+		this.messengerState.setIdentified(true, metadata);
 
-		// Start WebSocket now that we have a session token
 		if (this.apiService?.sessionToken && !this.wsService?.isConnected) {
 			this._initWebSocket();
 		}
@@ -850,7 +845,10 @@ export class MessengerWidget extends BaseWidget {
 	}
 
 	_hasExplicitOption(key) {
-		return Object.prototype.hasOwnProperty.call(this._explicitOptions || {}, key);
+		return Object.prototype.hasOwnProperty.call(
+			this._explicitOptions || {},
+			key
+		);
 	}
 
 	async checkAgentAvailability() {