@sessionsight/goals 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,106 @@
+# @sessionsight/goals
+
+Server-side SDK for tracking goal progress in SessionSight.
+
+## Installation
+
+```bash
+npm install @sessionsight/goals
+```
+
+Or with a script tag:
+
+```html
+<script src="https://cdn.sessionsight.com/sessionsight-goals.js"></script>
+```
+
+## Quick Start
+
+```typescript
+import SessionSightGoals from '@sessionsight/goals';
+
+// Initialize with your secret API key and property ID
+SessionSightGoals.init({
+  secretApiKey: 'sessionsight_sec_your_secret_key',
+  propertyId: 'your-property-id',
+});
+
+// Increment a goal
+await SessionSightGoals.increment('user-signups');
+
+// Increment with a custom amount
+await SessionSightGoals.increment('revenue', { amount: 49 });
+
+// Increment with a monetary value for revenue attribution
+await SessionSightGoals.increment('purchase', {
+  value: 49.99,
+  currency: 'USD',
+  metadata: { sku: 'widget-pro' },
+});
+
+// Increment with metadata
+await SessionSightGoals.increment('user-signups', {
+  metadata: { plan: 'pro', source: 'landing-page' },
+});
+```
+
+## API Reference
+
+### `SessionSightGoals.init(config)`
+
+Initialize the SDK. Must be called before any other method.
+
+| Option       | Type     | Required | Default                          | Description                    |
+| ------------ | -------- | -------- | -------------------------------- | ------------------------------ |
+| `secretApiKey`  | `string` | Yes      | —                                | Your secret API key (`sessionsight_sec_...`) |
+| `propertyId` | `string` | Yes      | —                                | The property ID to track       |
+| `apiUrl`     | `string` | No       | `https://api.sessionsight.com`   | Custom API endpoint            |
+
+### `SessionSightGoals.increment(goalId, options?)`
+
+Increment a goal counter. Returns a `Promise<IncrementResult>`.
+
+| Parameter            | Type                      | Required | Default | Description                     |
+| -------------------- | ------------------------- | -------- | ------- | ------------------------------- |
+| `goalId`             | `string`                  | Yes      | —       | The goal's slug ID              |
+| `options.amount`     | `number`                  | No       | `1`     | Amount to increment by          |
+| `options.value`      | `number`                  | No       | —       | Monetary value (e.g., purchase amount) |
+| `options.currency`   | `string`                  | No       | —       | ISO 4217 currency code (e.g., `'USD'`) |
+| `options.visitorId`  | `string`                  | No       | —       | SessionSight visitor ID for attribution |
+| `options.metadata`   | `Record<string, string>`  | No       | —       | Optional context for the event  |
+
+**Returns:**
+
+```typescript
+interface IncrementResult {
+  success: boolean;
+  error?: string;
+}
+```
+
+### `SessionSightGoals.decrement(goalId, options?)`
+
+Decrement a goal counter. Returns a `Promise<IncrementResult>`.
+
+| Parameter            | Type                      | Required | Default | Description                     |
+| -------------------- | ------------------------- | -------- | ------- | ------------------------------- |
+| `goalId`             | `string`                  | Yes      | —       | The goal's slug ID              |
+| `options.amount`     | `number`                  | No       | `1`     | Amount to decrement by          |
+| `options.visitorId`  | `string`                  | No       | —       | SessionSight visitor ID for attribution |
+| `options.metadata`   | `Record<string, string>`  | No       | —       | Optional context for the event  |
+
+### `SessionSightGoals.destroy()`
+
+Tear down the SDK instance. Call this during cleanup if needed.
+
+## Authentication
+
+This SDK uses your **secret API key** (`sessionsight_sec_...`), not the public key. The secret key should only be used in server-side code — never expose it in client-side JavaScript.
+
+## Build Outputs
+
+| File                          | Format | Usage                                              |
+| ----------------------------- | ------ | -------------------------------------------------- |
+| `dist/index.js`               | ESM    | `import SessionSightGoals from '@sessionsight/goals'` |
+| `dist/index.d.ts`             | Types  | TypeScript type definitions                        |
+| `dist/sessionsight-goals.js`  | IIFE   | `<script>` tag → `window.SessionSightGoals`        |

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sessionsight/goals",
+  "version": "1.0.0",
+  "description": "Goal and conversion tracking SDK for SessionSight.",
+  "author": "SessionSight",
+  "license": "MIT",
+  "homepage": "https://sessionsight.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SessionSight/sdks.git",
+    "directory": "packages/goals"
+  },
+  "bugs": {
+    "url": "https://github.com/SessionSight/sdks/issues"
+  },
+  "keywords": [
+    "goals",
+    "conversion-tracking",
+    "analytics",
+    "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,104 @@
+import type { GoalsConfig, IncrementOptions, DecrementOptions, IncrementResult } from './types.js';
+import { normalizeApiUrl } 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 GoalsClient {
+  private apiUrl: string;
+  private secretApiKey: string;
+  private propertyId: string;
+
+  constructor(config: GoalsConfig) {
+    if (typeof window !== 'undefined' && !('process' in globalThis)) {
+      throw new Error('@sessionsight/goals is a server-side SDK and cannot be used in the browser.');
+    }
+    if (!config.secretApiKey?.trim()) throw new Error('@sessionsight/goals: secretApiKey is required.');
+    if (!config.propertyId?.trim()) throw new Error('@sessionsight/goals: propertyId is required.');
+    this.secretApiKey = config.secretApiKey;
+    this.propertyId = config.propertyId;
+    this.apiUrl = normalizeApiUrl(config.apiUrl || '');
+  }
+
+  async increment(goalId: string, options?: IncrementOptions): Promise<IncrementResult> {
+    const amount = options?.amount ?? 1;
+    if (!Number.isFinite(amount) || amount <= 0) {
+      return { success: false, error: 'amount must be a positive finite number' };
+    }
+    if (options?.value != null && (!Number.isFinite(options.value) || options.value < 0)) {
+      return { success: false, error: 'value must be a non-negative finite number' };
+    }
+    try {
+      const res = await fetchWithTimeout(`${this.apiUrl}/v1/goals/increment`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.secretApiKey,
+        },
+        body: JSON.stringify({
+          goalId,
+          propertyId: this.propertyId,
+          amount: options?.amount ?? 1,
+          ...(options?.value != null ? { value: options.value } : {}),
+          ...(options?.currency ? { currency: options.currency } : {}),
+          ...(options?.visitorId ? { visitorId: options.visitorId } : {}),
+          ...(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 Goals] Failed to increment goal:', message);
+      return { success: false, error: message };
+    }
+  }
+
+  async decrement(goalId: string, options?: DecrementOptions): Promise<IncrementResult> {
+    const amount = options?.amount ?? 1;
+    if (!Number.isFinite(amount) || amount <= 0) {
+      return { success: false, error: 'amount must be a positive finite number' };
+    }
+    try {
+      const res = await fetchWithTimeout(`${this.apiUrl}/v1/goals/decrement`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.secretApiKey,
+        },
+        body: JSON.stringify({
+          goalId,
+          propertyId: this.propertyId,
+          amount: options?.amount ?? 1,
+          ...(options?.visitorId ? { visitorId: options.visitorId } : {}),
+          ...(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 Goals] Failed to decrement goal:', 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,42 @@
+import { GoalsClient } from './client.js';
+import type { GoalsConfig, IncrementOptions, DecrementOptions, IncrementResult } from './types.js';
+
+export { GoalsClient };
+export type { GoalsConfig, IncrementOptions, DecrementOptions, IncrementResult } from './types.js';
+
+let instance: GoalsClient | null = null;
+
+const SessionSightGoals = {
+  init(config: GoalsConfig): void {
+    if (instance) {
+      console.warn('[SessionSight Goals] Already initialized. Call destroy() first.');
+      return;
+    }
+    instance = new GoalsClient(config);
+  },
+
+  async increment(goalId: string, options?: IncrementOptions): Promise<IncrementResult> {
+    if (!instance) {
+      console.warn('[SessionSight Goals] Not initialized. Call init() first.');
+      return { success: false, error: 'Not initialized' };
+    }
+    return instance.increment(goalId, options);
+  },
+
+  async decrement(goalId: string, options?: DecrementOptions): Promise<IncrementResult> {
+    if (!instance) {
+      console.warn('[SessionSight Goals] Not initialized. Call init() first.');
+      return { success: false, error: 'Not initialized' };
+    }
+    return instance.decrement(goalId, options);
+  },
+
+  destroy(): void {
+    if (instance) {
+      instance.destroy();
+      instance = null;
+    }
+  },
+};
+
+export default SessionSightGoals;

package/src/types.ts

@@ -0,0 +1,24 @@
+export interface GoalsConfig {
+  secretApiKey: string;
+  propertyId: string;
+  apiUrl?: string;
+}
+
+export interface IncrementOptions {
+  amount?: number;
+  value?: number;
+  currency?: string;
+  visitorId?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface DecrementOptions {
+  amount?: number;
+  visitorId?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface IncrementResult {
+  success: boolean;
+  error?: string;
+}

package/test/client.test.ts

@@ -0,0 +1,198 @@
+import { test, expect, mock, beforeEach } from 'bun:test';
+import { GoalsClient } from '../src/client.js';
+
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+test('increment sends correct request', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+    apiUrl: 'https://api.example.com',
+  });
+
+  const result = await client.increment('user-signups');
+
+  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/goals/increment');
+  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.goalId).toBe('user-signups');
+  expect(body.propertyId).toBe('prop-1');
+  expect(body.amount).toBe(1);
+});
+
+test('increment sends custom amount and metadata', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.increment('revenue', { amount: 49, metadata: { plan: 'pro' } });
+
+  const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+  expect(body.amount).toBe(49);
+  expect(body.metadata).toEqual({ plan: 'pro' });
+});
+
+test('increment returns error on non-ok response', async () => {
+  globalThis.fetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ error: 'Goal not found' }), { status: 404 }))
+  );
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  const result = await client.increment('nonexistent');
+  expect(result.success).toBe(false);
+  expect(result.error).toBe('Goal not found');
+});
+
+test('increment returns error on network failure', async () => {
+  globalThis.fetch = mock(() => Promise.reject(new Error('Network error')));
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  const result = await client.increment('user-signups');
+  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 GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+    apiUrl: 'https://api.example.com/',
+  });
+
+  await client.increment('test');
+  const url = (mockFetch.mock.calls[0] as [string, RequestInit])[0];
+  expect(url).toBe('https://api.example.com/v1/goals/increment');
+});
+
+test('increment sends value and currency for revenue attribution', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.increment('purchase', { value: 49.99, currency: 'USD', metadata: { sku: 'widget-pro' } });
+
+  const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+  expect(body.value).toBe(49.99);
+  expect(body.currency).toBe('USD');
+  expect(body.metadata).toEqual({ sku: 'widget-pro' });
+  expect(body.amount).toBe(1);
+});
+
+test('increment omits value and currency when not provided', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.increment('user-signups', { amount: 5 });
+
+  const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+  expect(body.value).toBeUndefined();
+  expect(body.currency).toBeUndefined();
+  expect(body.amount).toBe(5);
+});
+
+test('decrement sends correct request', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+    apiUrl: 'https://api.example.com',
+  });
+
+  const result = await client.decrement('user-signups');
+
+  expect(result).toEqual({ success: true });
+  const [url, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
+  expect(url).toBe('https://api.example.com/v1/goals/decrement');
+  expect(opts.method).toBe('POST');
+  const body = JSON.parse(opts.body as string);
+  expect(body.goalId).toBe('user-signups');
+  expect(body.propertyId).toBe('prop-1');
+  expect(body.amount).toBe(1);
+});
+
+test('decrement sends custom amount and metadata', async () => {
+  const mockFetch = mock(() =>
+    Promise.resolve(new Response(JSON.stringify({ success: true }), { status: 200 }))
+  );
+  globalThis.fetch = mockFetch;
+
+  const client = new GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.decrement('inventory', { amount: 3, metadata: { reason: 'refund' } });
+
+  const body = JSON.parse((mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string);
+  expect(body.amount).toBe(3);
+  expect(body.metadata).toEqual({ reason: 'refund' });
+});
+
+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 GoalsClient({
+    secretApiKey: 'sk_test_123',
+    propertyId: 'prop-1',
+  });
+
+  await client.increment('test');
+  const url = (mockFetch.mock.calls[0] as [string, RequestInit])[0];
+  expect(url).toBe('https://api.sessionsight.com/v1/goals/increment');
+});

package/tsconfig.json

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