@sessionsight/feedback 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SessionSight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @sessionsight/feedback
+
+Collect structured feedback, bug reports, and ratings from your users.
+
+## Installation
+
+```bash
+npm install @sessionsight/feedback
+```
+
+## Quick Start
+
+```typescript
+import SessionSightFeedback from '@sessionsight/feedback';
+
+SessionSightFeedback.init({
+  secretApiKey: 'sessionsight_sec_...',
+  propertyId: 'your-property-id',
+});
+
+// Submit feedback
+await SessionSightFeedback.submit('bug-report', {
+  userId: 'user_456',
+  option: 'critical',
+  message: 'The checkout page crashes on Safari',
+  metadata: { page: '/checkout', browser: 'Safari 17' },
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `secretApiKey` | `string` | **required** | Your secret API key from the dashboard |
+| `propertyId` | `string` | **required** | Your property ID |
+| `apiUrl` | `string` | `https://api.sessionsight.com` | Override for self-hosted or local dev |
+
+## API
+
+### `SessionSightFeedback.init(config)`
+
+Initialize the SDK with your credentials.
+
+### `SessionSightFeedback.submit(feedbackTypeId, options?)`
+
+Submit feedback.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `feedbackTypeId` | `string` | Yes | The feedback type slug (created in the dashboard) |
+| `options.userId` | `string` | No | Identifier for the user submitting the feedback |
+| `options.visitorId` | `string` | No | SessionSight visitor ID for session attribution |
+| `options.sessionId` | `string` | No | SessionSight session ID to link feedback to a specific session |
+| `options.option` | `string` | No | Selected option value (must match a pre-defined option) |
+| `options.message` | `string` | No | Free-text message (only if the feedback type allows text input) |
+| `options.metadata` | `Record<string, string>` | No | Additional key-value context |
+
+Returns `Promise<{ success: boolean; error?: string }>`.
+
+### `SessionSightFeedback.destroy()`
+
+Clean up resources.
+
+## Class-based Usage
+
+```typescript
+import { FeedbackClient } from '@sessionsight/feedback';
+
+const feedback = new FeedbackClient({
+  secretApiKey: 'sessionsight_sec_...',
+  propertyId: 'your-property-id',
+});
+
+await feedback.submit('star-rating', { option: '5', userId: 'user_123' });
+
+feedback.destroy();
+```
+
+## Use Cases
+
+### Bug Reports
+
+```typescript
+await SessionSightFeedback.submit('bug-report', {
+  userId: 'user_123',
+  option: 'critical',
+  message: 'Payment fails with Amex cards',
+  metadata: { page: '/checkout', browser: 'Chrome 120' },
+});
+```
+
+### Star Ratings (1-5)
+
+```typescript
+await SessionSightFeedback.submit('star-rating', {
+  option: '4',
+  userId: 'user_123',
+});
+```
+
+### Sentiment Feedback (Good/Neutral/Bad)
+
+```typescript
+await SessionSightFeedback.submit('page-feedback', {
+  option: 'good',
+  userId: 'user_123',
+  message: 'This article was really helpful!',
+});
+```
+
+## Script Tag
+
+```html
+<script src="https://cdn.sessionsight.com/sessionsight-feedback.js"></script>
+<script>
+  SessionSightFeedback.init({
+    secretApiKey: 'sessionsight_sec_...',
+    propertyId: 'your-property-id',
+  });
+</script>
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sessionsight/feedback",
+  "version": "1.0.0",
+  "description": "User feedback and survey SDK for SessionSight.",
+  "author": "SessionSight",
+  "license": "MIT",
+  "homepage": "https://sessionsight.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SessionSight/sdks.git",
+    "directory": "packages/feedback"
+  },
+  "bugs": {
+    "url": "https://github.com/SessionSight/sdks/issues"
+  },
+  "keywords": [
+    "feedback",
+    "surveys",
+    "user-feedback",
+    "sessionsight"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --format esm && bun x tsc --emitDeclarationOnly --declaration --outDir dist"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@sessionsight/sdk-shared": "workspace:*"
+  }
+}

package/src/client.ts

@@ -0,0 +1,64 @@
+import type { FeedbackConfig, FeedbackOptions, FeedbackResult } from './types.js';
+import { normalizeApiUrl, getOrCreateVisitorId } from '@sessionsight/sdk-shared';
+
+const FETCH_TIMEOUT_MS = 10_000;
+
+function fetchWithTimeout(url: string, options: RequestInit): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(timer));
+}
+
+export class FeedbackClient {
+  private apiUrl: string;
+  private secretApiKey: string;
+  private propertyId: string;
+
+  constructor(config: FeedbackConfig) {
+    if (typeof window !== 'undefined' && !('process' in globalThis)) {
+      throw new Error('@sessionsight/feedback is a server-side SDK and cannot be used in the browser.');
+    }
+    if (!config.secretApiKey?.trim()) throw new Error('@sessionsight/feedback: secretApiKey is required.');
+    if (!config.propertyId?.trim()) throw new Error('@sessionsight/feedback: propertyId is required.');
+    this.secretApiKey = config.secretApiKey;
+    this.propertyId = config.propertyId;
+    this.apiUrl = normalizeApiUrl(config.apiUrl || '');
+  }
+
+  async submit(feedbackTypeId: string, options?: FeedbackOptions): Promise<FeedbackResult> {
+    try {
+      const res = await fetchWithTimeout(`${this.apiUrl}/v1/feedback/submit`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.secretApiKey,
+        },
+        body: JSON.stringify({
+          feedbackTypeId,
+          propertyId: this.propertyId,
+          visitorId: options?.visitorId || getOrCreateVisitorId(),
+          ...(options?.userId ? { userId: options.userId } : {}),
+          ...(options?.sessionId ? { sessionId: options.sessionId } : {}),
+          ...(options?.option ? { option: options.option } : {}),
+          ...(options?.message ? { message: options.message } : {}),
+          ...(options?.metadata ? { metadata: options.metadata } : {}),
+        }),
+      });
+
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        return { success: false, error: (data as any).error || `HTTP ${res.status}` };
+      }
+
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error';
+      console.warn('[SessionSight Feedback] Failed to submit feedback:', message);
+      return { success: false, error: message };
+    }
+  }
+
+  destroy(): void {
+    // No-op for now; reserved for future cleanup (e.g., batching, intervals)
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import { FeedbackClient } from './client.js';
+import type { FeedbackConfig, FeedbackOptions, FeedbackResult } from './types.js';
+
+export { FeedbackClient };
+export type { FeedbackConfig, FeedbackOptions, FeedbackResult } from './types.js';
+
+let instance: FeedbackClient | null = null;
+
+const SessionSightFeedback = {
+  init(config: FeedbackConfig): void {
+    if (instance) {
+      console.warn('[SessionSight Feedback] Already initialized. Call destroy() first.');
+      return;
+    }
+    instance = new FeedbackClient(config);
+  },
+
+  async submit(feedbackTypeId: string, options?: FeedbackOptions): Promise<FeedbackResult> {
+    if (!instance) {
+      console.warn('[SessionSight Feedback] Not initialized. Call init() first.');
+      return { success: false, error: 'Not initialized' };
+    }
+    return instance.submit(feedbackTypeId, options);
+  },
+
+  destroy(): void {
+    if (instance) {
+      instance.destroy();
+      instance = null;
+    }
+  },
+};
+
+export default SessionSightFeedback;

package/src/types.ts

@@ -0,0 +1,19 @@
+export interface FeedbackConfig {
+  secretApiKey: string;
+  propertyId: string;
+  apiUrl?: string;
+}
+
+export interface FeedbackOptions {
+  userId?: string;
+  visitorId?: string;
+  sessionId?: string;
+  option?: string;
+  message?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface FeedbackResult {
+  success: boolean;
+  error?: string;
+}

package/test/client.test.ts

@@ -0,0 +1,150 @@
+import { test, expect, mock, beforeEach } from 'bun:test';
+import { FeedbackClient } from '../src/client.js';
+
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+test('submit sends correct request', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+    apiUrl: 'https://api.example.com',
+  });
+
+  const result = await client.submit('bug-report', {
+    userId: 'user_456',
+    option: 'critical',
+    message: 'Page crashes on Safari',
+    metadata: { page: '/checkout' },
+  });
+
+  expect(result).toEqual({ success: true });
+  expect(mockFetch).toHaveBeenCalledTimes(1);
+
+  const [url, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
+  expect(url).toBe('https://api.example.com/v1/feedback/submit');
+  expect(opts.method).toBe('POST');
+  expect(opts.headers).toEqual({
+    'Content-Type': 'application/json',
+    'x-api-key': 'sk_test_123',
+  });
+  const body = JSON.parse(opts.body as string);
+  expect(body.feedbackTypeId).toBe('bug-report');
+  expect(body.propertyId).toBe('prop-1');
+  expect(body.userId).toBe('user_456');
+  expect(body.option).toBe('critical');
+  expect(body.message).toBe('Page crashes on Safari');
+  expect(body.metadata).toEqual({ page: '/checkout' });
+});
+
+test('submit with no options sends minimal payload', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.submit('general');
+
+  const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+  expect(body.feedbackTypeId).toBe('general');
+  expect(body.propertyId).toBe('prop-1');
+  expect(body.userId).toBeUndefined();
+  expect(body.option).toBeUndefined();
+  expect(body.message).toBeUndefined();
+  expect(body.metadata).toBeUndefined();
+});
+
+test('submit returns error on non-ok response', async () => {
+  globalThis.fetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ error: 'Feedback type not found' }), { status: 404 }))
+  );
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  const result = await client.submit('nonexistent');
+  expect(result.success).toBe(false);
+  expect(result.error).toBe('Feedback type not found');
+});
+
+test('submit returns error on network failure', async () => {
+  globalThis.fetch = mock(() => Promise.reject(new Error('Network error')));
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  const result = await client.submit('bug-report');
+  expect(result.success).toBe(false);
+  expect(result.error).toBe('Network error');
+});
+
+test('strips trailing slash from apiUrl', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+    apiUrl: 'https://api.example.com/',
+  });
+
+  await client.submit('test');
+  const url = (mockFetch.mock.calls[0] as [string, RequestInit])[0];
+  expect(url).toBe('https://api.example.com/v1/feedback/submit');
+});
+
+test('uses default apiUrl when not provided', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.submit('test');
+  const url = (mockFetch.mock.calls[0] as [string, RequestInit])[0];
+  expect(url).toBe('https://api.sessionsight.com/v1/feedback/submit');
+});
+
+test('submit only includes provided optional fields', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new FeedbackClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.submit('star-rating', { option: '5' });
+
+  const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+  expect(body.feedbackTypeId).toBe('star-rating');
+  expect(body.option).toBe('5');
+  expect(body.userId).toBeUndefined();
+  expect(body.message).toBeUndefined();
+  expect(body.metadata).toBeUndefined();
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "noEmit": false,
+    "rootDir": "./src",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}