> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cutmeshort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Official TypeScript SDK for CutMeShort API

## Installation

```bash theme={null}
npm install cutmeshort
```

## Requirements

* Node.js 18+ (recommended) or any runtime with global `fetch`
* TypeScript 5+ (optional, for type safety)

## Quick Start

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({
  apiKey: process.env.CMS_API_KEY!,
});
```

## Non-Deferred Lead Tracking

Use non-deferred lead tracking when you can send the `clickId` at the moment you want to record a lead event.

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({ apiKey: "sk_live_xxx" });

const response = await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerExternalId: "user_42",
  timestamp: new Date().toISOString(),
  customerName: "John Doe",
  customerEmail: "john@example.com"
});
```

### Lead Payload Fields

* `clickId: string` - The unique click identifier
* `eventName: string` - Name of the lead event (e.g., "signup\_started", "email\_verified")
* `customerExternalId: string` - Your internal customer identifier
* `timestamp?: string` - ISO 8601 timestamp (defaults to current time)
* `customerName?: string` - Full name of the customer
* `customerEmail?: string` - Customer's email address

## Deferred Lead Tracking

Use deferred mode when you can't reliably send the `clickId` at the moment of recording a lead event. This enables two-step lead attribution.

### Step 1: Store the clickId Association

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({ apiKey: "sk_live_xxx" });

// Store the clickId <-> customerExternalId association
await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerExternalId: "user_42",
  mode: "deferred",
});
```

### Step 2: Track Using Only customerExternalId

```typescript theme={null}
// Later, track using just customerExternalId (no clickId needed)
await cms.trackLead({
  eventName: "email_verified",
  customerExternalId: "user_42",
});
```

**Key Differences:**

* In deferred mode's first call, you associate a `clickId` with a `customerExternalId`
* In subsequent calls, you only need the `customerExternalId` the SDK will use the stored association
* This is useful for complex user journeys where the click context may be lost

## Sale Tracking

Track sales/conversions with detailed transaction information.

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({ apiKey: "sk_live_xxx" });

await cms.trackSale({
  customerExternalId: "user_123",
  eventName: "purchase_completed",
  invoiceId: "inv_987",
  amount: 4999,
  currency: "USD",
  timestamp: new Date().toISOString(),
  customerName: "Jane Smith",
  customerEmail: "jane@example.com"
});
```

### Sale Payload Fields

* `eventName: string` - Name of the sale event (e.g., "purchase\_completed")
* `customerExternalId: string` - Your internal customer identifier
* `invoiceId: string` - Invoice or transaction identifier
* `amount: number` - Amount in cents (e.g., 4999 = \$49.99)
* `currency: string` - 3-letter currency code (e.g., "USD", "EUR", "GBP")
* `timestamp?: string` - ISO 8601 timestamp (defaults to current time)
* `customerName?: string` - Customer's name
* `customerEmail?: string` - Customer's email

## Error Handling

```typescript theme={null}
import { CMS, CMSAPIError } from "cutmeshort";

const cms = new CMS({ apiKey: process.env.CMS_API_KEY });

try {
  await cms.trackLead({
    clickId: "id_123",
    eventName: "signup_started",
    customerExternalId: "user_42",
  });
} catch (error) {
  if (error instanceof CMSAPIError) {
    console.error("CMS API error", {
      statusCode: error.statusCode,
      type: error.type,
      message: error.message,
    });
  } else {
    console.error("Unexpected error", error);
  }
}
```

## Documentation

For complete documentation, visit [TypeScript SDK Docs](https://github.com/Cut-Me-Short/cms-ts)