@product7/feedback-sdk 1.4.3 → 1.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@product7/feedback-sdk",
-	"version": "1.4.3",
+	"version": "1.4.5",
 	"description": "JavaScript SDK for integrating Product7 feedback widgets into any website",
 	"main": "dist/feedback-sdk.js",
 	"module": "src/index.js",

package/src/docs/framework-integrations.md

@@ -0,0 +1,707 @@
+# Framework Integrations
+
+Use this document to integrate `@product7/feedback-sdk` in supported frontend frameworks.
+
+This guide includes:
+
+1. Next.js
+2. React
+3. Vue + Nuxt
+4. Angular
+5. Svelte + SvelteKit
+6. Astro
+
+## Before You Start
+
+Install the SDK:
+
+```bash
+npm install @product7/feedback-sdk
+```
+
+Prepare your runtime values:
+
+- `workspace` (required)
+- `boardId` (recommended for feedback button)
+- `userContext` (recommended for personalization and messenger)
+
+Example configuration:
+
+```ts
+const sdkConfig = {
+	workspace: 'your-workspace',
+	boardId: 'feature-requests',
+	debug: false,
+	userContext: {
+		user_id: 'user_123',
+		email: 'user@example.com',
+		name: 'Jane Doe',
+		custom_fields: {
+			plan: 'pro',
+			role: 'admin',
+		},
+		company: {
+			id: 'company_123',
+			name: 'Acme Inc',
+		},
+	},
+};
+```
+
+Integration rules:
+
+- Run SDK initialization on the client side only.
+- Always call `await sdk.init()` before creating widgets.
+- Prefer a single shared SDK instance per app session.
+- Destroy widgets and SDK on app teardown where applicable.
+
+## Framework-Specific Configuration
+
+Use framework-native environment variables so values stay deployment-safe.
+
+### Next.js
+
+- Use `NEXT_PUBLIC_*` for client-side values.
+- Build `userContext` from your auth/session payload.
+- When logged-in user changes, call `sdk.setUserContext(nextUserContext)`.
+
+```ts
+const sdkConfig = {
+	workspace: process.env.NEXT_PUBLIC_PRODUCT7_WORKSPACE!,
+	boardId: process.env.NEXT_PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
+	debug: process.env.NEXT_PUBLIC_PRODUCT7_DEBUG === 'true',
+	userContext: {
+		user_id: session.user.id,
+		email: session.user.email,
+		name: session.user.name,
+	},
+};
+```
+
+### React (Vite / CRA)
+
+- Vite: use `import.meta.env.VITE_*`.
+- CRA: use `process.env.REACT_APP_*`.
+- Keep config in one helper so all components use the same values.
+
+```ts
+const sdkConfig = {
+	workspace: import.meta.env.VITE_PRODUCT7_WORKSPACE,
+	boardId: import.meta.env.VITE_PRODUCT7_BOARD_ID || 'feature-requests',
+	debug: import.meta.env.DEV,
+	userContext: currentUser
+		? {
+				user_id: currentUser.id,
+				email: currentUser.email,
+				name: currentUser.name,
+			}
+		: undefined,
+};
+```
+
+### Vue + Nuxt
+
+- Vue (Vite): use `import.meta.env.VITE_*`.
+- Nuxt: use `useRuntimeConfig().public`.
+- In Nuxt, initialize in a `.client` plugin and expose SDK through `provide`.
+
+```ts
+// Nuxt example
+const runtime = useRuntimeConfig();
+const sdkConfig = {
+	workspace: runtime.public.product7Workspace,
+	boardId: runtime.public.product7BoardId || 'feature-requests',
+	debug: runtime.public.product7Debug === 'true',
+	userContext,
+};
+```
+
+### Angular
+
+- Keep SDK values in `environment.ts` and `environment.prod.ts`.
+- Map app auth user into `userContext` in your singleton service.
+
+```ts
+const sdkConfig = {
+	workspace: environment.product7.workspace,
+	boardId: environment.product7.boardId || 'feature-requests',
+	debug: !environment.production,
+	userContext: {
+		user_id: user.id,
+		email: user.email,
+		name: user.fullName,
+	},
+};
+```
+
+### Svelte + SvelteKit
+
+- Svelte: use `import.meta.env.VITE_*`.
+- SvelteKit: use `$env/static/public` (or `$env/dynamic/public`) values.
+- Reuse one config builder in `+layout.svelte` to avoid repeated setup.
+
+```ts
+const sdkConfig = {
+	workspace: PUBLIC_PRODUCT7_WORKSPACE,
+	boardId: PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
+	debug: PUBLIC_PRODUCT7_DEBUG === 'true',
+	userContext,
+};
+```
+
+### Astro
+
+- Expose client-safe values with `PUBLIC_*`.
+- Run SDK code only in client-loaded components (`client:load` / `client:visible`).
+
+```ts
+const sdkConfig = {
+	workspace: import.meta.env.PUBLIC_PRODUCT7_WORKSPACE,
+	boardId: import.meta.env.PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
+	debug: import.meta.env.PUBLIC_PRODUCT7_DEBUG === 'true',
+	userContext,
+};
+```
+
+### Optional SDK Keys You Can Add Per Framework
+
+- `apiUrl`: custom API endpoint override.
+- `env`: force `'staging'` or `'production'`.
+- `mock`: enable mock responses for local development.
+- `theme`: default `'light'` or `'dark'`.
+- `position`: default widget position.
+
+## 1) Next.js
+
+### App Router
+
+Create a client provider:
+
+`app/providers.tsx`
+
+```tsx
+'use client';
+
+import { useEffect, useRef } from 'react';
+import FeedbackSDK from '@product7/feedback-sdk';
+
+export function FeedbackProvider() {
+	const sdkRef = useRef<any>(null);
+	const widgetRef = useRef<any>(null);
+
+	useEffect(() => {
+		let cancelled = false;
+
+		(async () => {
+			const sdk = FeedbackSDK.create({
+				workspace: 'your-workspace',
+				boardId: 'feature-requests',
+				userContext: {
+					user_id: 'user_123',
+					email: 'user@example.com',
+					name: 'Jane Doe',
+				},
+			});
+
+			await sdk.init();
+			if (cancelled) {
+				sdk.destroy();
+				return;
+			}
+
+			sdkRef.current = sdk;
+			widgetRef.current = sdk.createWidget('button', {
+				position: 'bottom-right',
+			});
+			widgetRef.current.mount();
+		})();
+
+		return () => {
+			cancelled = true;
+			widgetRef.current?.destroy();
+			sdkRef.current?.destroy();
+		};
+	}, []);
+
+	return null;
+}
+```
+
+Render provider in layout:
+
+`app/layout.tsx`
+
+```tsx
+import { FeedbackProvider } from './providers';
+
+export default function RootLayout({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	return (
+		<html lang="en">
+			<body>
+				<FeedbackProvider />
+				{children}
+			</body>
+		</html>
+	);
+}
+```
+
+### Pages Router
+
+`pages/_app.tsx`
+
+```tsx
+import type { AppProps } from 'next/app';
+import { useEffect } from 'react';
+import FeedbackSDK from '@product7/feedback-sdk';
+
+export default function App({ Component, pageProps }: AppProps) {
+	useEffect(() => {
+		const sdk = FeedbackSDK.create({
+			workspace: 'your-workspace',
+			boardId: 'feature-requests',
+			userContext: { user_id: 'user_123', email: 'user@example.com' },
+		});
+
+		let widget: any;
+		(async () => {
+			await sdk.init();
+			widget = sdk.createWidget('button', { position: 'bottom-right' });
+			widget.mount();
+		})();
+
+		return () => {
+			widget?.destroy();
+			sdk.destroy();
+		};
+	}, []);
+
+	return <Component {...pageProps} />;
+}
+```
+
+## 2) React
+
+`src/App.tsx`
+
+```tsx
+import { useEffect, useRef } from 'react';
+import FeedbackSDK from '@product7/feedback-sdk';
+
+export default function App() {
+	const sdkRef = useRef<any>(null);
+
+	useEffect(() => {
+		let widget: any;
+
+		(async () => {
+			const sdk = FeedbackSDK.create({
+				workspace: 'your-workspace',
+				boardId: 'feature-requests',
+				userContext: {
+					user_id: 'user_123',
+					email: 'user@example.com',
+					name: 'Jane Doe',
+				},
+			});
+
+			await sdk.init();
+			sdkRef.current = sdk;
+
+			widget = sdk.createWidget('button', {
+				position: 'bottom-right',
+			});
+			widget.mount();
+		})();
+
+		return () => {
+			widget?.destroy();
+			sdkRef.current?.destroy();
+		};
+	}, []);
+
+	return <main>My App</main>;
+}
+```
+
+## 3) Vue + Nuxt
+
+### Vue
+
+`src/App.vue`
+
+```vue
+<script setup lang="ts">
+	import { onMounted, onUnmounted, ref } from 'vue';
+	import FeedbackSDK from '@product7/feedback-sdk';
+
+	const sdk = ref<any>(null);
+	const widget = ref<any>(null);
+
+	onMounted(async () => {
+		sdk.value = FeedbackSDK.create({
+			workspace: 'your-workspace',
+			boardId: 'feature-requests',
+			userContext: {
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'Jane Doe',
+			},
+		});
+
+		await sdk.value.init();
+		widget.value = sdk.value.createWidget('button', {
+			position: 'bottom-right',
+		});
+		widget.value.mount();
+	});
+
+	onUnmounted(() => {
+		widget.value?.destroy();
+		sdk.value?.destroy();
+	});
+</script>
+
+<template>
+	<div>My App</div>
+</template>
+```
+
+### Nuxt
+
+Create a client plugin:
+
+`plugins/feedback.client.ts`
+
+```ts
+import FeedbackSDK from '@product7/feedback-sdk';
+
+export default defineNuxtPlugin(async () => {
+	const sdk = FeedbackSDK.create({
+		workspace: 'your-workspace',
+		boardId: 'feature-requests',
+		userContext: {
+			user_id: 'user_123',
+			email: 'user@example.com',
+			name: 'Jane Doe',
+		},
+	});
+
+	await sdk.init();
+
+	return {
+		provide: {
+			feedbackSDK: sdk,
+		},
+	};
+});
+```
+
+Mount a widget in `app.vue` (or a layout):
+
+```vue
+<script setup lang="ts">
+	const { $feedbackSDK } = useNuxtApp();
+	let widget: any;
+
+	onMounted(() => {
+		widget = $feedbackSDK.createWidget('button', {
+			position: 'bottom-right',
+			boardId: 'feature-requests',
+		});
+		widget.mount();
+	});
+
+	onBeforeUnmount(() => {
+		widget?.destroy();
+	});
+</script>
+```
+
+For larger Nuxt apps, use a Pinia store with `isReady` checks to avoid duplicate widget creation.
+
+## 4) Angular
+
+Create a singleton service:
+
+`feedback.service.ts`
+
+```ts
+import { Injectable } from '@angular/core';
+import FeedbackSDK from '@product7/feedback-sdk';
+
+@Injectable({ providedIn: 'root' })
+export class FeedbackService {
+	private sdk: any = null;
+	private buttonWidget: any = null;
+
+	async init() {
+		if (this.sdk) return;
+
+		this.sdk = FeedbackSDK.create({
+			workspace: 'your-workspace',
+			boardId: 'feature-requests',
+			userContext: {
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'Jane Doe',
+			},
+		});
+
+		await this.sdk.init();
+	}
+
+	mountButton() {
+		if (!this.sdk || this.buttonWidget) return;
+		this.buttonWidget = this.sdk.createWidget('button', {
+			position: 'bottom-right',
+		});
+		this.buttonWidget.mount();
+	}
+
+	destroy() {
+		this.buttonWidget?.destroy();
+		this.buttonWidget = null;
+		this.sdk?.destroy();
+		this.sdk = null;
+	}
+}
+```
+
+Use it in the root component:
+
+`app.component.ts`
+
+```ts
+import { Component, OnDestroy, OnInit } from '@angular/core';
+import { FeedbackService } from './feedback.service';
+
+@Component({
+	selector: 'app-root',
+	template: '<router-outlet></router-outlet>',
+})
+export class AppComponent implements OnInit, OnDestroy {
+	constructor(private feedback: FeedbackService) {}
+
+	async ngOnInit() {
+		await this.feedback.init();
+		this.feedback.mountButton();
+	}
+
+	ngOnDestroy() {
+		this.feedback.destroy();
+	}
+}
+```
+
+## 5) Svelte + SvelteKit
+
+### Svelte
+
+`src/App.svelte`
+
+```svelte
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import FeedbackSDK from '@product7/feedback-sdk';
+
+	let sdk: any = null;
+	let widget: any = null;
+
+	onMount(() => {
+		let disposed = false;
+
+		(async () => {
+			sdk = FeedbackSDK.create({
+				workspace: 'your-workspace',
+				boardId: 'feature-requests',
+				userContext: {
+					user_id: 'user_123',
+					email: 'user@example.com',
+					name: 'Jane Doe',
+				},
+			});
+
+			await sdk.init();
+			if (disposed) return;
+
+			widget = sdk.createWidget('button', { position: 'bottom-right' });
+			widget.mount();
+		})();
+
+		return () => {
+			disposed = true;
+			widget?.destroy();
+			sdk?.destroy();
+		};
+	});
+</script>
+
+<main>My App</main>
+```
+
+### SvelteKit
+
+`src/routes/+layout.svelte`
+
+```svelte
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import { onMount } from 'svelte';
+	import FeedbackSDK from '@product7/feedback-sdk';
+
+	let sdk: any;
+	let widget: any;
+
+	onMount(() => {
+		if (!browser) return;
+
+		(async () => {
+			sdk = FeedbackSDK.create({
+				workspace: 'your-workspace',
+				boardId: 'feature-requests',
+				userContext: {
+					user_id: 'user_123',
+					email: 'user@example.com',
+				},
+			});
+
+			await sdk.init();
+			widget = sdk.createWidget('button', { position: 'bottom-right' });
+			widget.mount();
+		})();
+
+		return () => {
+			widget?.destroy();
+			sdk?.destroy();
+		};
+	});
+</script>
+
+<slot />
+```
+
+## 6) Astro
+
+Astro renders on the server by default, so initialize the SDK from a client-loaded component.
+
+`src/components/FeedbackWidget.astro`
+
+```astro
+<script>
+	import FeedbackSDK from '@product7/feedback-sdk';
+
+	let sdk;
+	let widget;
+
+	(async () => {
+		sdk = FeedbackSDK.create({
+			workspace: 'your-workspace',
+			boardId: 'feature-requests',
+			userContext: {
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'Jane Doe',
+			},
+		});
+
+		await sdk.init();
+		widget = sdk.createWidget('button', { position: 'bottom-right' });
+		widget.mount();
+	})();
+</script>
+```
+
+Use the component in a page:
+
+```astro
+---
+import FeedbackWidget from '../components/FeedbackWidget.astro';
+---
+
+<html lang="en">
+	<body>
+		<FeedbackWidget client:load />
+	</body>
+</html>
+```
+
+## Add More Widgets (Any Framework)
+
+You can create survey, messenger, and changelog widgets from the same SDK instance:
+
+```ts
+const survey = sdk.createWidget('survey', {
+	surveyType: 'nps',
+	position: 'center',
+	theme: 'light',
+	title: 'How likely are you to recommend us?',
+	description: 'Your feedback helps us improve.',
+	lowLabel: 'Not likely',
+	highLabel: 'Very likely',
+	onSubmit: (response) => {
+		console.log('Survey submitted:', response);
+		// Optional: send to analytics
+		// analytics.track('survey_submitted', { type: response.type, score: response.score });
+	},
+	onDismiss: () => {
+		console.log('Survey dismissed');
+	},
+});
+survey.show();
+// survey.hide();
+// survey.destroy();
+
+const messenger = sdk.createWidget('messenger', {
+	position: 'bottom-right',
+	theme: 'light',
+	teamName: 'Support Team',
+	welcomeMessage: 'How can we help?',
+	enableHelp: true,
+	enableChangelog: true,
+	primaryColor: '#155EEF',
+	onSendMessage: (conversationId, message) => {
+		console.log('Message sent:', conversationId, message);
+	},
+	onArticleClick: (article) => {
+		console.log('Article clicked:', article);
+	},
+	onChangelogClick: (item) => {
+		console.log('Changelog clicked:', item);
+	},
+});
+messenger.mount();
+// messenger.open();
+// messenger.navigateTo('help');
+// messenger.close();
+
+const changelog = sdk.createWidget('changelog', {
+	position: 'bottom-left',
+	theme: 'light',
+	triggerText: "What's New",
+	showBadge: true,
+	title: "What's New",
+	viewButtonText: 'View Update',
+	onViewUpdate: (item) => {
+		console.log('Viewed changelog item:', item);
+	},
+});
+changelog.mount();
+// changelog.openSidebar();
+// changelog.closeSidebar();
+```
+
+## Troubleshooting
+
+- `SDK must be initialized before creating widgets`
+  Call `await sdk.init()` before any `createWidget(...)` call.
+- Widget not visible
+  Make sure you call `widget.mount()` for mounted widget types.
+- `window is not defined` or `document is not defined`
+  Move SDK code to client-only lifecycle hooks/components.
+- Duplicate widget instances
+  Cache widget references and guard against double mount.