@vigneshreddy/cms-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CutMeShort
+
+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,217 @@
+# CMS TypeScript SDK (cms)
+
+TypeScript/JavaScript SDK for the CutMeShort CMS API.
+
+This SDK is:
+- Fetch-based (uses native `fetch`).
+- Typed (TypeScript types for requests/responses).
+- Resilient (built-in retries for transient errors).
+
+## Install
+
+```bash
+npm install cms
+```
+
+## Publish to npm
+
+```bash
+npm login
+npm run build
+npm publish --access public
+```
+
+## Runtime requirements
+
+- Browser: any modern browser with `fetch`.
+- Node.js: Node 18+ recommended (built-in `fetch`).
+- Node < 18: add a fetch polyfill and set it globally before using the SDK.
+
+```ts
+import fetch, { Headers, Request, Response } from "cross-fetch";
+
+// @ts-ignore
+global.fetch = fetch as any;
+// @ts-ignore
+global.Headers = Headers as any;
+// @ts-ignore
+global.Request = Request as any;
+// @ts-ignore
+global.Response = Response as any;
+```
+
+## Quick start
+
+Create the client once and reuse it across calls.
+
+```ts
+import { CMS } from "cms";
+
+const sdk = new CMS({
+  apiKey: process.env.CMS_API_KEY!,
+  timeout: 10_000,
+});
+```
+
+## Track a lead
+
+### Class-based usage (throws on error)
+
+```ts
+import { CMS } from "cms";
+
+const sdk = new CMS({ apiKey: "sk_live_123" });
+
+const leadResponse = await sdk.trackLead({
+  clickId: "dub_123",
+  eventName: "signup_started",
+  customerId: "user_42",
+});
+
+console.log("Lead response:", leadResponse);
+```
+
+### Functional helper (Result pattern)
+
+```ts
+import { CMS, trackLead } from "cms";
+
+const sdk = new CMS({ apiKey: "sk_live_123" });
+
+const res = await trackLead(sdk, {
+  clickId: "dub_123",
+  eventName: "signup_started",
+  customerId: "user_42",
+});
+
+if (res.ok) {
+  console.log("Lead response:", res.value);
+} else {
+  console.error("Lead error:", res.error);
+}
+```
+
+## Track a sale
+
+### Class-based usage (throws on error)
+
+```ts
+import { CMS } from "cms";
+
+const sdk = new CMS({ apiKey: "sk_live_123" });
+
+const saleResponse = await sdk.trackSale({
+  clickId: "dub_123",
+  eventName: "purchase_completed",
+  invoiceId: "inv_987",
+  amount: 4999,
+  currency: "USD",
+});
+
+console.log("Sale response:", saleResponse);
+```
+
+### Functional helper (Result pattern)
+
+```ts
+import { CMS, trackSale } from "cms";
+
+const sdk = new CMS({ apiKey: "sk_live_123" });
+
+const res = await trackSale(sdk, {
+  clickId: "dub_123",
+  eventName: "purchase_completed",
+  invoiceId: "inv_987",
+  amount: 4999,
+  currency: "USD",
+});
+
+if (res.ok) {
+  console.log("Sale response:", res.value);
+} else {
+  console.error("Sale error:", res.error);
+}
+```
+
+## Configuration
+
+```ts
+export interface CMSConfig {
+  apiKey: string;
+  timeout?: number;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  retryOnStatuses?: number[];
+  retryOnNetworkError?: boolean;
+}
+```
+
+- `apiKey` (required): CMS secret API key.
+- `timeout`: request timeout in ms (default: 10000).
+- `maxRetries`: retry attempts for transient failures (default: 2).
+- `retryDelayMs`: base delay for linear backoff (default: 500).
+- `retryOnStatuses`: HTTP codes that are retryable (default: 429, 500, 502, 503, 504).
+- `retryOnNetworkError`: retry on network/timeout errors (default: true).
+
+## Per-request overrides
+
+You can override retries and timeout on a single request.
+
+```ts
+import { CMS } from "cms";
+
+const sdk = new CMS({ apiKey: "sk_live_123" });
+
+await sdk.trackLead(
+  {
+    clickId: "dub_123",
+    eventName: "signup_started",
+    customerId: "user_42",
+  },
+  {
+    timeout: 5000,
+    maxRetries: 1,
+  }
+);
+```
+
+## Error handling
+
+All thrown errors from class-based methods are normalized as `CMSAPIError` or its specific subclasses.
+
+```ts
+import { CMS, CMSAPIError } from "cms";
+
+const sdk = new CMS({ apiKey: "sk_live_123" });
+
+try {
+  await sdk.trackLead({
+    clickId: "dub_123",
+    eventName: "signup_started",
+    customerId: "user_42",
+  });
+} catch (err) {
+  if (err instanceof CMSAPIError) {
+    console.error("CMS API Error:", {
+      statusCode: err.statusCode,
+      type: err.type,
+      message: err.message,
+    });
+  } else {
+    console.error("Unexpected error:", err);
+  }
+}
+```
+
+## Exports
+
+```ts
+import { CMS } from "cms";
+import { trackLead, trackSale } from "cms";
+import { CMSAPIError } from "cms";
+import type { TrackLeadRequest, TrackSaleRequest, TrackResponse } from "cms";
+```
+
+## Security
+
+Do not expose secret API keys in frontend code. Use a backend or secure proxy if the key is private.

package/dist/src/client.d.ts

@@ -0,0 +1,46 @@
+import { EventsApi, TrackLeadRequest, TrackSaleRequest } from "./generated";
+export interface CMSConfig {
+    apiKey: string;
+    /**
+     * Optional timeout in milliseconds for HTTP requests.
+     * This is implemented using AbortController around the native fetch API.
+     */
+    timeout?: number;
+    /** Maximum number of retry attempts for transient failures */
+    maxRetries?: number;
+    /** Base delay (in ms) between retries for transient failures */
+    retryDelayMs?: number;
+    /** HTTP status codes that should be retried */
+    retryOnStatuses?: number[];
+    /** Whether to retry on network errors (no response / timeout) */
+    retryOnNetworkError?: boolean;
+}
+/**
+ * Per-request options that can override default SDK configuration
+ */
+export interface RequestOptions {
+    /** Override timeout for this specific request */
+    timeout?: number;
+    /** Override max retries for this specific request */
+    maxRetries?: number;
+    /** Override retry delay for this specific request */
+    retryDelayMs?: number;
+    /** Override retry status codes for this specific request */
+    retryOnStatuses?: number[];
+    /** Override retry on network error setting for this specific request */
+    retryOnNetworkError?: boolean;
+}
+export declare class CMS {
+    readonly events: EventsApi;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly retryOnStatuses;
+    private readonly retryOnNetworkError;
+    constructor(config: CMSConfig);
+    private isRetryableError;
+    private sleep;
+    private withRetry;
+    private isRetryableErrorWithOptions;
+    trackLead(request: TrackLeadRequest, options?: RequestOptions): Promise<import("./generated").TrackResponse>;
+    trackSale(request: TrackSaleRequest, options?: RequestOptions): Promise<import("./generated").TrackResponse>;
+}

package/dist/src/client.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CMS = void 0;
+// src/client.ts
+const generated_1 = require("./generated");
+const errors_1 = require("./errors");
+class CMS {
+    constructor(config) {
+        var _a, _b, _c, _d, _e;
+        if (!config.apiKey) {
+            throw new Error("CMS SDK: apiKey is required.");
+        }
+        const basePath = "https://www.cutmeshort.com/api";
+        // Retry configuration with sensible defaults
+        this.maxRetries = (_a = config.maxRetries) !== null && _a !== void 0 ? _a : 2;
+        this.retryDelayMs = (_b = config.retryDelayMs) !== null && _b !== void 0 ? _b : 500;
+        this.retryOnStatuses = new Set((_c = config.retryOnStatuses) !== null && _c !== void 0 ? _c : [429, 500, 502, 503, 504]);
+        this.retryOnNetworkError = (_d = config.retryOnNetworkError) !== null && _d !== void 0 ? _d : true;
+        // Create the Configuration object
+        const apiConfig = new generated_1.Configuration({
+            basePath,
+            accessToken: config.apiKey,
+            baseOptions: {
+                // Ensure generated client uses the same timeout & headers
+                timeout: (_e = config.timeout) !== null && _e !== void 0 ? _e : 10000,
+                headers: {
+                    'User-Agent': 'CMS-Node-SDK/1.0.0',
+                    'Content-Type': 'application/json'
+                },
+            },
+        });
+        // Instantiate the EventsApi using configuration and basePath.
+        // The underlying implementation uses the global `fetch` API.
+        this.events = new generated_1.EventsApi(apiConfig, basePath);
+    }
+    isRetryableError(error) {
+        var _a;
+        const axiosError = error;
+        // Network / timeout errors
+        if (this.retryOnNetworkError && (!axiosError.response || axiosError.code === "ECONNABORTED")) {
+            return true;
+        }
+        // HTTP status based retries
+        const status = (_a = axiosError.response) === null || _a === void 0 ? void 0 : _a.status;
+        if (status && this.retryOnStatuses.has(status)) {
+            return true;
+        }
+        return false;
+    }
+    async sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async withRetry(fn, options) {
+        var _a, _b, _c;
+        let attempt = 0;
+        // Use per-request options if provided, otherwise use instance defaults
+        const maxRetries = (_a = options === null || options === void 0 ? void 0 : options.maxRetries) !== null && _a !== void 0 ? _a : this.maxRetries;
+        const retryDelayMs = (_b = options === null || options === void 0 ? void 0 : options.retryDelayMs) !== null && _b !== void 0 ? _b : this.retryDelayMs;
+        const retryOnStatuses = (options === null || options === void 0 ? void 0 : options.retryOnStatuses)
+            ? new Set(options.retryOnStatuses)
+            : this.retryOnStatuses;
+        const retryOnNetworkError = (_c = options === null || options === void 0 ? void 0 : options.retryOnNetworkError) !== null && _c !== void 0 ? _c : this.retryOnNetworkError;
+        // attempt 0 + maxRetries additional retries
+        // e.g. maxRetries=2 -> attempts: 0,1,2
+        const maxAttempts = maxRetries + 1;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                attempt += 1;
+                // Check if error is retryable with current settings
+                const isRetryable = this.isRetryableErrorWithOptions(error, retryOnStatuses, retryOnNetworkError);
+                if (attempt >= maxAttempts || !isRetryable) {
+                    // Final failure, let our error handler wrap it
+                    return (0, errors_1.handleApiError)(error);
+                }
+                const delay = retryDelayMs * attempt; // simple linear backoff
+                await this.sleep(delay);
+            }
+        }
+    }
+    isRetryableErrorWithOptions(error, retryOnStatuses, retryOnNetworkError) {
+        var _a;
+        const axiosError = error;
+        // Network / timeout errors
+        if (retryOnNetworkError && (!axiosError.response || axiosError.code === "ECONNABORTED")) {
+            return true;
+        }
+        // HTTP status based retries
+        const status = (_a = axiosError.response) === null || _a === void 0 ? void 0 : _a.status;
+        if (status && retryOnStatuses.has(status)) {
+            return true;
+        }
+        return false;
+    }
+    async trackLead(request, options) {
+        return this.withRetry(async () => {
+            return this.events.trackLead(request);
+        }, options);
+    }
+    async trackSale(request, options) {
+        return this.withRetry(async () => {
+            return this.events.trackSale(request);
+        }, options);
+    }
+}
+exports.CMS = CMS;

package/dist/src/errors/base.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base error class for CMS API errors.
+ * Separated into its own file to avoid circular dependencies.
+ */
+export declare class CMSAPIError extends Error {
+    readonly statusCode: number;
+    readonly type: string;
+    readonly rawError: any;
+    readonly request?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, any>;
+    };
+    readonly response?: {
+        status: number;
+        statusText: string;
+        data?: any;
+        headers?: Record<string, any>;
+    };
+    constructor(message: string, statusCode: number, type: string, rawError: any, request?: CMSAPIError["request"], response?: CMSAPIError["response"]);
+}

package/dist/src/errors/base.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CMSAPIError = void 0;
+/**
+ * Base error class for CMS API errors.
+ * Separated into its own file to avoid circular dependencies.
+ */
+class CMSAPIError extends Error {
+    constructor(message, statusCode, type, rawError, request, response) {
+        super(message);
+        this.name = "CMSAPIError";
+        this.statusCode = statusCode;
+        this.type = type;
+        this.rawError = rawError;
+        this.request = request;
+        this.response = response;
+    }
+}
+exports.CMSAPIError = CMSAPIError;

package/dist/src/errors/index.d.ts

@@ -0,0 +1,3 @@
+export { CMSAPIError } from "./base";
+export { handleApiError } from "../errors";
+export { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, createSpecificError, } from "./specific";

package/dist/src/errors/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpecificError = exports.GatewayTimeoutError = exports.ServiceUnavailableError = exports.BadGatewayError = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = exports.handleApiError = exports.CMSAPIError = void 0;
+// Re-export base error
+var base_1 = require("./base");
+Object.defineProperty(exports, "CMSAPIError", { enumerable: true, get: function () { return base_1.CMSAPIError; } });
+var errors_1 = require("../errors");
+Object.defineProperty(exports, "handleApiError", { enumerable: true, get: function () { return errors_1.handleApiError; } });
+// Specific error types
+var specific_1 = require("./specific");
+Object.defineProperty(exports, "BadRequestError", { enumerable: true, get: function () { return specific_1.BadRequestError; } });
+Object.defineProperty(exports, "UnauthorizedError", { enumerable: true, get: function () { return specific_1.UnauthorizedError; } });
+Object.defineProperty(exports, "ForbiddenError", { enumerable: true, get: function () { return specific_1.ForbiddenError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return specific_1.NotFoundError; } });
+Object.defineProperty(exports, "ConflictError", { enumerable: true, get: function () { return specific_1.ConflictError; } });
+Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, get: function () { return specific_1.UnprocessableEntityError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return specific_1.RateLimitError; } });
+Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return specific_1.InternalServerError; } });
+Object.defineProperty(exports, "BadGatewayError", { enumerable: true, get: function () { return specific_1.BadGatewayError; } });
+Object.defineProperty(exports, "ServiceUnavailableError", { enumerable: true, get: function () { return specific_1.ServiceUnavailableError; } });
+Object.defineProperty(exports, "GatewayTimeoutError", { enumerable: true, get: function () { return specific_1.GatewayTimeoutError; } });
+Object.defineProperty(exports, "createSpecificError", { enumerable: true, get: function () { return specific_1.createSpecificError; } });

package/dist/src/errors/specific.d.ts

@@ -0,0 +1,43 @@
+import { CMSAPIError } from "./base";
+export { CMSAPIError };
+/**
+ * Specific error types for different HTTP status codes.
+ * These provide better type safety and allow users to handle specific errors.
+ */
+export declare class BadRequestError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class UnauthorizedError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class ForbiddenError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class NotFoundError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class ConflictError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class UnprocessableEntityError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class RateLimitError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class InternalServerError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class BadGatewayError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class ServiceUnavailableError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+export declare class GatewayTimeoutError extends CMSAPIError {
+    constructor(message: string, rawError?: any);
+}
+/**
+ * Maps HTTP status codes to specific error classes
+ */
+export declare function createSpecificError(statusCode: number, message: string, rawError?: any): CMSAPIError;

package/dist/src/errors/specific.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayTimeoutError = exports.ServiceUnavailableError = exports.BadGatewayError = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = exports.CMSAPIError = void 0;
+exports.createSpecificError = createSpecificError;
+const base_1 = require("./base");
+Object.defineProperty(exports, "CMSAPIError", { enumerable: true, get: function () { return base_1.CMSAPIError; } });
+/**
+ * Specific error types for different HTTP status codes.
+ * These provide better type safety and allow users to handle specific errors.
+ */
+class BadRequestError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 400, "bad_request", rawError);
+        this.name = "BadRequestError";
+    }
+}
+exports.BadRequestError = BadRequestError;
+class UnauthorizedError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 401, "unauthorized", rawError);
+        this.name = "UnauthorizedError";
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+class ForbiddenError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 403, "forbidden", rawError);
+        this.name = "ForbiddenError";
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+class NotFoundError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 404, "not_found", rawError);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ConflictError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 409, "conflict", rawError);
+        this.name = "ConflictError";
+    }
+}
+exports.ConflictError = ConflictError;
+class UnprocessableEntityError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 422, "unprocessable_entity", rawError);
+        this.name = "UnprocessableEntityError";
+    }
+}
+exports.UnprocessableEntityError = UnprocessableEntityError;
+class RateLimitError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 429, "rate_limit_exceeded", rawError);
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
+class InternalServerError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 500, "internal_server_error", rawError);
+        this.name = "InternalServerError";
+    }
+}
+exports.InternalServerError = InternalServerError;
+class BadGatewayError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 502, "bad_gateway", rawError);
+        this.name = "BadGatewayError";
+    }
+}
+exports.BadGatewayError = BadGatewayError;
+class ServiceUnavailableError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 503, "service_unavailable", rawError);
+        this.name = "ServiceUnavailableError";
+    }
+}
+exports.ServiceUnavailableError = ServiceUnavailableError;
+class GatewayTimeoutError extends base_1.CMSAPIError {
+    constructor(message, rawError) {
+        super(message, 504, "gateway_timeout", rawError);
+        this.name = "GatewayTimeoutError";
+    }
+}
+exports.GatewayTimeoutError = GatewayTimeoutError;
+/**
+ * Maps HTTP status codes to specific error classes
+ */
+function createSpecificError(statusCode, message, rawError) {
+    switch (statusCode) {
+        case 400:
+            return new BadRequestError(message, rawError);
+        case 401:
+            return new UnauthorizedError(message, rawError);
+        case 403:
+            return new ForbiddenError(message, rawError);
+        case 404:
+            return new NotFoundError(message, rawError);
+        case 409:
+            return new ConflictError(message, rawError);
+        case 422:
+            return new UnprocessableEntityError(message, rawError);
+        case 429:
+            return new RateLimitError(message, rawError);
+        case 500:
+            return new InternalServerError(message, rawError);
+        case 502:
+            return new BadGatewayError(message, rawError);
+        case 503:
+            return new ServiceUnavailableError(message, rawError);
+        case 504:
+            return new GatewayTimeoutError(message, rawError);
+        default:
+            return new base_1.CMSAPIError(message, statusCode, "api_error", rawError);
+    }
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,8 @@
+import { CMSAPIError } from "./errors/base";
+export { CMSAPIError };
+export { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, BadGatewayError, ServiceUnavailableError, GatewayTimeoutError, createSpecificError, } from "./errors/index";
+/**
+ * Parses fetch/network errors into a clean CMSAPIError
+ * Uses specific error types when possible for better type safety
+ */
+export declare function handleApiError(error: any, request?: any, response?: any): never;