npm package: @sessionsight/goals
Description: Goal and conversion tracking SDK for SessionSight.
Author: SessionSight
Latest version: 1.0.1

# @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`        |