@vigneshreddy/cms-sdk

Official TypeScript/JavaScript SDK for the CutMeShort CMS API.

Use this package to send:

• lead tracking events (cms.trackLead)
• sale tracking events (cms.trackSale)

Install

npm install @vigneshreddy/cms-sdk

Requirements

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

If your runtime does not provide fetch, add a polyfill before creating the client.

import fetch, { Headers, Request, Response } from "cross-fetch";

(globalThis as any).fetch = fetch;
(globalThis as any).Headers = Headers;
(globalThis as any).Request = Request;
(globalThis as any).Response = Response;

Quick Start

import { CMS } from "@vigneshreddy/cms-sdk";

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

const response = await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerId: "user_42",
});

console.log(response);

API Methods

cms.trackLead(leadData, options?)

import { CMS } from "@vigneshreddy/cms-sdk";

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

await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerId: "user_42",
});

Lead payload fields:

• clickId: string (optional in deferred follow-up calls)
• eventName: string
• customerId: string
• timestamp?: string (ISO 8601, e.g. new Date().toISOString())
• customerExternalId?: string
• customerName?: string
• customerEmail?: string
• customerAvatar?: string

Deferred mode (two-step lead attribution)

If you can’t reliably send the clickId at the moment you want to record a lead event, you can use deferred mode:

import { CMS } from "@vigneshreddy/cms-sdk";

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

// Step 1: store the clickId <-> customerId association
await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerId: "user_42",
  mode: "deferred",
});

// Step 2: later, track using just customerId (no clickId)
await cms.trackLead({
  eventName: "email_verified",
  customerId: "user_42",
  mode: "deferred",
});

cms.trackSale(saleData, options?)

import { CMS } from "@vigneshreddy/cms-sdk";

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

await cms.trackSale({
  clickId: "id_123",
  eventName: "purchase_completed",
  invoiceId: "inv_987",
  amount: 4999,
  currency: "USD",
});

Sale payload fields:

• clickId: string
• eventName: string
• timestamp?: string (ISO 8601, e.g. new Date().toISOString())
• customerExternalId?: string
• customerName?: string
• customerEmail?: string
• customerAvatar?: string
• invoiceId: string
• amount: number (in cents)
• currency: string (3-letter code, e.g. USD)

Configuration

new CMS(config) accepts:

type CMSConfig = {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
  maxRetries?: number;
  retryDelayMs?: number;
  retryMaxDelayMs?: number;
  retryOnStatuses?: number[];
  retryOnNetworkError?: boolean;
};

Defaults:

• baseUrl: https://www.cutmeshort.com/sdk
• timeout: 10000
• maxRetries: 2
• retryDelayMs: 500
• retryMaxDelayMs: 10000
• retryOnStatuses: [429, 500, 502, 503, 504]
• retryOnNetworkError: true

Per-request Overrides

You can override retry/timeout settings for a specific call:

import { CMS } from "@vigneshreddy/cms-sdk";

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

await cms.trackLead(
  {
    clickId: "id_123",
    eventName: "signup_started",
    customerId: "user_42",
  },
  {
    timeout: 5000,
    maxRetries: 1,
    retryDelayMs: 300,
  }
);

Error Handling

Class-based methods (cms.trackLead, cms.trackSale) throw CMSAPIError on failure.

import { CMS, CMSAPIError } from "@vigneshreddy/cms-sdk";

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

try {
  await cms.trackSale({
    clickId: "id_123",
    eventName: "purchase_completed",
    invoiceId: "inv_987",
    amount: 4999,
    currency: "USD",
  });
} 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);
  }
}

Public API

This package intentionally exposes only:

• CMS (use cms.trackLead and cms.trackSale)
• CMSAPIError (for instanceof checks)

Deep imports (example: @vigneshreddy/cms-sdk/client) are intentionally blocked.

Security Best Practice

Do not expose private API keys in public frontend code. Use this SDK from a trusted backend/server environment when using secret keys.