@vigneshreddy/cms-sdk 1.0.14 → 1.0.15

package/README.md

@@ -1,10 +1,20 @@
 # @vigneshreddy/cms-sdk
 
-Official TypeScript/JavaScript SDK for the CutMeShort CMS API.
+[![npm version](https://img.shields.io/npm/v/@vigneshreddy/cms-sdk)](https://www.npmjs.com/package/@vigneshreddy/cms-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
 
-Use this package to send:
-- lead tracking events (`cms.trackLead`)
-- sale tracking events (`cms.trackSale`)
+Official TypeScript/JavaScript SDK for the CutMeShort CMS API. Track leads and sales with reliable retry logic, comprehensive validation, and security best practices.
+
+**Key Features:**
+- 🚀 Full TypeScript support with strict types
+- ✅ Input validation with Zod
+- 🔄 Automatic retry with exponential backoff
+- 🛡️ Security hardened (API key validation, sensitive data redaction)
+- ⚡ Sub-second tracking events
+- 📊 Comprehensive error handling with specific error types
+
+---
 
 ## Install
 
@@ -41,7 +51,7 @@ const cms = new CMS({
 const response = await cms.trackLead({
   clickId: "id_123",
   eventName: "signup_started",
-  customerId: "user_42",
+  customerExternalId: "user_42",
 });
 
 console.log(response);
@@ -59,16 +69,15 @@ const cms = new CMS({ apiKey: "sk_live_xxx" });
 await cms.trackLead({
   clickId: "id_123",
   eventName: "signup_started",
-  customerId: "user_42",
+  customerExternalId: "user_42",
 });
 ```
 
 Lead payload fields:
 - `clickId: string` (optional in **deferred** follow-up calls)
 - `eventName: string`
-- `customerId: string`
+- `customerExternalId: string`
 - `timestamp?: string` (ISO 8601, e.g. `new Date().toISOString()`)
-- `customerExternalId?: string`
 - `customerName?: string`
 - `customerEmail?: string`
 - `customerAvatar?: string`
@@ -82,18 +91,18 @@ import { CMS } from "@vigneshreddy/cms-sdk";
 
 const cms = new CMS({ apiKey: "sk_live_xxx" });
 
-// Step 1: store the clickId <-> customerId association
+// Step 1: store the clickId <-> customerExternalId association
 await cms.trackLead({
   clickId: "id_123",
   eventName: "signup_started",
-  customerId: "user_42",
+  customerExternalId: "user_42",
   mode: "deferred",
 });
 
-// Step 2: later, track using just customerId (no clickId)
+// Step 2: later, track using just customerExternalId (no clickId)
 await cms.trackLead({
   eventName: "email_verified",
-  customerId: "user_42",
+  customerExternalId: "user_42",
   mode: "deferred",
 });
 ```
@@ -103,10 +112,11 @@ await cms.trackLead({
 ```ts
 import { CMS } from "@vigneshreddy/cms-sdk";
 
-const cms = new CMS({ apiKey: "sk_live_xxx" });
+const cms = new CMS({ apiKey: "xxx" });
 
 await cms.trackSale({
   clickId: "id_123",
+  customerExternalId: "user_123",
   eventName: "purchase_completed",
   invoiceId: "inv_987",
   amount: 4999,
@@ -118,7 +128,7 @@ Sale payload fields:
 - `clickId: string`
 - `eventName: string`
 - `timestamp?: string` (ISO 8601, e.g. `new Date().toISOString()`)
-- `customerExternalId?: string`
+- `customerExternalId: string`
 - `customerName?: string`
 - `customerEmail?: string`
 - `customerAvatar?: string`
@@ -144,7 +154,7 @@ type CMSConfig = {
 ```
 
 Defaults:
-- `baseUrl`: `https://www.cutmeshort.com/sdk`
+- `baseUrl`: `https://www.cutmeshort.com`
 - `timeout`: `10000`
 - `maxRetries`: `2`
 - `retryDelayMs`: `500`
@@ -165,7 +175,7 @@ await cms.trackLead(
   {
     clickId: "id_123",
     eventName: "signup_started",
-    customerId: "user_42",
+    customerExternalId: "user_42",
   },
   {
     timeout: 5000,
@@ -177,42 +187,117 @@ await cms.trackLead(
 
 ## Error Handling
 
-Class-based methods (`cms.trackLead`, `cms.trackSale`) throw `CMSAPIError` on failure.
+The SDK provides specific error classes for different failure scenarios. Catch and handle them appropriately:
 
 ```ts
-import { CMS, CMSAPIError } from "@vigneshreddy/cms-sdk";
+import { 
+  CMS, 
+  CMSAPIError,
+  UnauthorizedError,
+  RateLimitError,
+  ValidationError 
+} from "@vigneshreddy/cms-sdk";
 
-const cms = new CMS({ apiKey: "sk_live_xxx" });
+const cms = new CMS({ apiKey: process.env.CMS_API_KEY });
 
 try {
-  await cms.trackSale({
+  await cms.trackLead({
     clickId: "id_123",
-    eventName: "purchase_completed",
-    invoiceId: "inv_987",
-    amount: 4999,
-    currency: "USD",
+    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,
-    });
+  if (error instanceof UnauthorizedError) {
+    console.error("Invalid API key - check your credentials");
+  } else if (error instanceof RateLimitError) {
+    console.error("Rate limited - wait before retrying");
+  } else if (error instanceof CMSAPIError) {
+    console.error(`CMS API error [${error.statusCode}]:`, error.message);
+    console.debug("Type:", error.type);
   } else {
-    console.error("Unexpected error", error);
+    console.error("Unexpected error:", error);
   }
 }
 ```
 
+### Available Error Types
+
+| Error Type | HTTP Code | When It Happens |
+|---|---|---|
+| `BadRequestError` | 400 | Invalid payload format |
+| `UnauthorizedError` | 401 | Invalid/missing API key |
+| `ForbiddenError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | Resource already exists |
+| `UnprocessableEntityError` | 422 | Validation failed |
+| `RateLimitError` | 429 | Too many requests |
+| `InternalServerError` | 500 | Server error |
+| `BadGatewayError` | 502 | Gateway error (retried) |
+| `ServiceUnavailableError` | 503 | Service down (retried) |
+| `GatewayTimeoutError` | 504 | Timeout (retried) |
+
+**Note:** Errors with HTTP codes 429, 500, 502, 503, 504 are automatically retried (configurable).
+
+### Retry Behavior
+
+The SDK automatically retries transient failures with exponential backoff:
+
+```ts
+const cms = new CMS({
+  apiKey: process.env.CMS_API_KEY,
+  maxRetries: 2,           // default: 2
+  retryDelayMs: 500,       // initial delay: 500ms
+  retryMaxDelayMs: 10000,  // max delay cap: 10s
+  retryOnNetworkError: true,
+});
+
+// Override for a specific request
+await cms.trackLead(
+  { clickId: "id_123", eventName: "event", customerExternalId: "user_1" },
+  { maxRetries: 5, retryDelayMs: 1000 }
+);
+```
+## TypeScript Usage
+
+The SDK is fully typed. Utilize TypeScript for better DX:
+
+```ts
+import { 
+  CMS, 
+  type CMSConfig,
+  type LeadPayload,
+  type SalePayload,
+  type RequestOptions 
+} from "@vigneshreddy/cms-sdk";
+
+// Config is validated at initialization
+const config: CMSConfig = {
+  apiKey: process.env.CMS_API_KEY!,
+  timeout: 5000,
+  maxRetries: 3,
+};
+
+const cms = new CMS(config);
+
+// Payloads have full type hints
+const leadPayload: LeadPayload = {
+  clickId: "id_123",
+  eventName: "signup_started",
+  customerExteranlId: "user_42",
+  customerEmail: "user@example.com",
+};
+
+// RequestOptions for per-call configuration
+const options: RequestOptions = {
+  timeout: 3000,
+  maxRetries: 1,
+};
+
+await cms.trackLead(leadPayload, options);
+```
+
 ## 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.

package/dist/src/circuit-breaker.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Circuit breaker to prevent cascading failures
+ * Fails fast when backend is unhealthy
+ */
+export declare enum CircuitBreakerState {
+    CLOSED = "CLOSED",// Normal operation
+    OPEN = "OPEN",// Failing fast
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerOptions {
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time window to count failures (milliseconds) */
+    failureWindowMs: number;
+    /** Time to wait before attempting to recover (milliseconds) */
+    resetTimeoutMs: number;
+    /** Callback when state changes */
+    onStateChange?: (newState: CircuitBreakerState, reason?: string) => void;
+}
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private failureTimestamps;
+    private lastFailureTime;
+    private nextAttemptTime;
+    private failureThreshold;
+    private failureWindowMs;
+    private resetTimeoutMs;
+    private onStateChange?;
+    constructor(options: CircuitBreakerOptions);
+    /**
+     * Check if a request should be allowed
+     */
+    canAttempt(): boolean;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(): void;
+    /**
+     * Get current state
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Get number of recent failures
+     */
+    getFailureCount(): number;
+    /**
+     * Get milliseconds until circuit attempts to recover
+     */
+    getRecoveryTime(): number;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    private setState;
+}
+/**
+ * Pre-configured circuit breaker settings for common scenarios
+ */
+export declare const CIRCUIT_BREAKER_PRESETS: {
+    /**
+     * Strict: Open after 2 failures in 10 seconds, wait 30 seconds before retry
+     */
+    readonly STRICT: {
+        readonly failureThreshold: 2;
+        readonly failureWindowMs: 10000;
+        readonly resetTimeoutMs: 30000;
+    };
+    /**
+     * Standard: Open after 5 failures in 30 seconds, wait 60 seconds before retry
+     */
+    readonly STANDARD: {
+        readonly failureThreshold: 5;
+        readonly failureWindowMs: 30000;
+        readonly resetTimeoutMs: 60000;
+    };
+    /**
+     * Lenient: Open after 10 failures in 60 seconds, wait 120 seconds before retry
+     */
+    readonly LENIENT: {
+        readonly failureThreshold: 10;
+        readonly failureWindowMs: 60000;
+        readonly resetTimeoutMs: 120000;
+    };
+    /**
+     * Disabled: Circuit breaker always allows attempts
+     */
+    readonly DISABLED: {
+        readonly failureThreshold: number;
+        readonly failureWindowMs: number;
+        readonly resetTimeoutMs: 0;
+    };
+};

package/dist/src/circuit-breaker.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Circuit breaker to prevent cascading failures
+ * Fails fast when backend is unhealthy
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CIRCUIT_BREAKER_PRESETS = exports.CircuitBreaker = exports.CircuitBreakerState = void 0;
+var CircuitBreakerState;
+(function (CircuitBreakerState) {
+    CircuitBreakerState["CLOSED"] = "CLOSED";
+    CircuitBreakerState["OPEN"] = "OPEN";
+    CircuitBreakerState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitBreakerState || (exports.CircuitBreakerState = CircuitBreakerState = {}));
+class CircuitBreaker {
+    constructor(options) {
+        this.state = CircuitBreakerState.CLOSED;
+        this.failureCount = 0;
+        this.failureTimestamps = [];
+        this.lastFailureTime = 0;
+        this.nextAttemptTime = 0;
+        this.failureThreshold = options.failureThreshold;
+        this.failureWindowMs = options.failureWindowMs;
+        this.resetTimeoutMs = options.resetTimeoutMs;
+        this.onStateChange = options.onStateChange;
+    }
+    /**
+     * Check if a request should be allowed
+     */
+    canAttempt() {
+        if (this.state === CircuitBreakerState.CLOSED) {
+            return true;
+        }
+        if (this.state === CircuitBreakerState.OPEN) {
+            const now = Date.now();
+            if (now >= this.nextAttemptTime) {
+                // Try to recover
+                this.setState(CircuitBreakerState.HALF_OPEN, "Attempting recovery");
+                return true;
+            }
+            return false;
+        }
+        // HALF_OPEN - allow attempt
+        return true;
+    }
+    /**
+     * Record a successful request
+     */
+    recordSuccess() {
+        if (this.state === CircuitBreakerState.HALF_OPEN) {
+            this.setState(CircuitBreakerState.CLOSED, "Recovered successfully");
+        }
+        // Clear failure history on success
+        if (this.state === CircuitBreakerState.CLOSED) {
+            this.failureCount = 0;
+            this.failureTimestamps = [];
+        }
+    }
+    /**
+     * Record a failed request
+     */
+    recordFailure() {
+        const now = Date.now();
+        this.lastFailureTime = now;
+        // Remove old failures outside the window
+        this.failureTimestamps = this.failureTimestamps.filter((timestamp) => now - timestamp < this.failureWindowMs);
+        // Add new failure
+        this.failureTimestamps.push(now);
+        this.failureCount = this.failureTimestamps.length;
+        if (this.state === CircuitBreakerState.HALF_OPEN) {
+            // Failed during recovery attempt
+            this.setState(CircuitBreakerState.OPEN, "Recovery attempt failed");
+            this.nextAttemptTime = now + this.resetTimeoutMs;
+        }
+        else if (this.state === CircuitBreakerState.CLOSED) {
+            // Check if threshold exceeded
+            if (this.failureCount >= this.failureThreshold) {
+                this.setState(CircuitBreakerState.OPEN, `${this.failureCount} failures in ${this.failureWindowMs}ms`);
+                this.nextAttemptTime = now + this.resetTimeoutMs;
+            }
+        }
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get number of recent failures
+     */
+    getFailureCount() {
+        // Clean up old failures
+        const now = Date.now();
+        this.failureTimestamps = this.failureTimestamps.filter((timestamp) => now - timestamp < this.failureWindowMs);
+        return this.failureTimestamps.length;
+    }
+    /**
+     * Get milliseconds until circuit attempts to recover
+     */
+    getRecoveryTime() {
+        if (this.state !== CircuitBreakerState.OPEN) {
+            return 0;
+        }
+        return Math.max(0, this.nextAttemptTime - Date.now());
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset() {
+        this.setState(CircuitBreakerState.CLOSED, "Manual reset");
+        this.failureCount = 0;
+        this.failureTimestamps = [];
+        this.lastFailureTime = 0;
+        this.nextAttemptTime = 0;
+    }
+    setState(newState, reason) {
+        if (this.state !== newState) {
+            this.state = newState;
+            if (this.onStateChange) {
+                this.onStateChange(newState, reason);
+            }
+        }
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+/**
+ * Pre-configured circuit breaker settings for common scenarios
+ */
+exports.CIRCUIT_BREAKER_PRESETS = {
+    /**
+     * Strict: Open after 2 failures in 10 seconds, wait 30 seconds before retry
+     */
+    STRICT: {
+        failureThreshold: 2,
+        failureWindowMs: 10000,
+        resetTimeoutMs: 30000,
+    },
+    /**
+     * Standard: Open after 5 failures in 30 seconds, wait 60 seconds before retry
+     */
+    STANDARD: {
+        failureThreshold: 5,
+        failureWindowMs: 30000,
+        resetTimeoutMs: 60000,
+    },
+    /**
+     * Lenient: Open after 10 failures in 60 seconds, wait 120 seconds before retry
+     */
+    LENIENT: {
+        failureThreshold: 10,
+        failureWindowMs: 60000,
+        resetTimeoutMs: 120000,
+    },
+    /**
+     * Disabled: Circuit breaker always allows attempts
+     */
+    DISABLED: {
+        failureThreshold: Infinity,
+        failureWindowMs: Infinity,
+        resetTimeoutMs: 0,
+    },
+};

package/dist/src/client.d.ts

@@ -1,4 +1,4 @@
-import { EventsApi, TrackLeadRequest, TrackSaleRequest } from "./generated";
+import { EventsApi, TrackLeadRequest, TrackSaleRequest } from "./funcs";
 export type LeadPayload = TrackLeadRequest;
 export type SalePayload = TrackSaleRequest;
 export interface CMSConfig {
@@ -57,6 +57,6 @@ export declare class CMS {
     private toGeneratedRequestOptions;
     private withRetry;
     private isRetryableErrorWithOptions;
-    trackLead(leadData: LeadPayload, options?: RequestOptions): Promise<import("./generated").TrackResponse>;
-    trackSale(saleData: SalePayload, options?: RequestOptions): Promise<import("./generated").TrackResponse>;
+    trackLead(leadData: LeadPayload, options?: RequestOptions): Promise<import("./funcs").TrackResponse>;
+    trackSale(saleData: SalePayload, options?: RequestOptions): Promise<import("./funcs").TrackResponse>;
 }

package/dist/src/client.js

@@ -2,19 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CMS = void 0;
 // src/client.ts
-const generated_1 = require("./generated");
+const funcs_1 = require("./funcs");
 const errors_1 = require("./errors");
-const DEFAULT_BASE_URL = "https://www.cutmeshort.com";
-const DEFAULT_TIMEOUT_MS = 10000;
-const DEFAULT_MAX_RETRIES = 2;
-const DEFAULT_RETRY_DELAY_MS = 500;
-const DEFAULT_RETRY_MAX_DELAY_MS = 10000;
-const DEFAULT_RETRY_STATUSES = [429, 500, 502, 503, 504];
+const validation_1 = require("./validations/validation");
+const constants_1 = require("./constants/constants");
+const DEFAULT_BASE_URL = constants_1.API_CONFIG.BASE_URL;
+const DEFAULT_TIMEOUT_MS = constants_1.API_CONFIG.TIMEOUT_MS;
+const DEFAULT_MAX_RETRIES = constants_1.RETRY_CONFIG.MAX_RETRIES;
+const DEFAULT_RETRY_DELAY_MS = constants_1.RETRY_CONFIG.DELAY_MS;
+const DEFAULT_RETRY_MAX_DELAY_MS = constants_1.RETRY_CONFIG.MAX_DELAY_MS;
+const DEFAULT_RETRY_STATUSES = [...constants_1.RETRY_CONFIG.ON_STATUSES];
 class CMS {
     constructor(config) {
         var _a, _b, _c, _d;
-        if (!config.apiKey) {
-            throw new Error("CMS SDK: apiKey is required.");
+        // Validate configuration with strict schema
+        try {
+            (0, validation_1.validateCMSConfig)(config);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`CMS SDK: Invalid configuration - ${message}`);
         }
         const basePath = this.normalizeBaseUrl((_a = config.baseUrl) !== null && _a !== void 0 ? _a : DEFAULT_BASE_URL);
         // Retry configuration with sensible defaults
@@ -24,20 +31,22 @@ class CMS {
         this.retryOnStatuses = this.resolveRetryStatuses((_b = config.retryOnStatuses) !== null && _b !== void 0 ? _b : DEFAULT_RETRY_STATUSES);
         this.retryOnNetworkError = (_c = config.retryOnNetworkError) !== null && _c !== void 0 ? _c : true;
         // Create the Configuration object
-        const apiConfig = new generated_1.Configuration({
+        const apiConfig = new funcs_1.Configuration({
             basePath,
             accessToken: config.apiKey,
             baseOptions: {
                 // Ensure generated client uses the same timeout & headers
                 timeout: (_d = config.timeout) !== null && _d !== void 0 ? _d : DEFAULT_TIMEOUT_MS,
                 headers: {
-                    'Content-Type': 'application/json'
+                    'Content-Type': 'application/json',
+                    'X-CMS-SDK-Version': constants_1.SDK_VERSION,
+                    'X-CMS-SDK-Runtime': typeof globalThis !== 'undefined' ? constants_1.HTTP_HEADERS.RUNTIME_NODEJS : constants_1.HTTP_HEADERS.RUNTIME_BROWSER,
                 },
             },
         });
         // Instantiate the EventsApi using configuration and basePath.
         // The underlying implementation uses the global `fetch` API.
-        this.events = new generated_1.EventsApi(apiConfig, basePath);
+        this.events = new funcs_1.EventsApi(apiConfig, basePath);
     }
     async sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
@@ -182,12 +191,28 @@ class CMS {
         return false;
     }
     async trackLead(leadData, options) {
+        // Validate lead data
+        try {
+            (0, validation_1.validateLeadPayload)(leadData);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`CMS SDK: Invalid lead data - ${message}`);
+        }
         const requestOptions = this.toGeneratedRequestOptions(options);
         return this.withRetry(async () => {
             return this.events.trackLead(leadData, requestOptions);
         }, options);
     }
     async trackSale(saleData, options) {
+        // Validate sale data
+        try {
+            (0, validation_1.validateSalePayload)(saleData);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`CMS SDK: Invalid sale data - ${message}`);
+        }
         const requestOptions = this.toGeneratedRequestOptions(options);
         return this.withRetry(async () => {
             return this.events.trackSale(saleData, requestOptions);