@kudosapi/sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KudosAPI
+
+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,152 @@
+# @kudosapi/sdk
+
+Official SDK for [KudosAPI](https://kudosapi.com) - Get positive notifications when good things happen in your app.
+
+## Installation
+
+```bash
+npm install @kudosapi/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Kudos } from '@kudosapi/sdk';
+
+const kudos = new Kudos({ apiKey: 'kudo_live_xxx' });
+
+// Track a sale
+await kudos.track({
+  type: 'sale',
+  title: 'New Pro subscription',
+  value: 99,
+  currency: 'USD',
+  data: { customer: 'jane@example.com' }
+});
+```
+
+## Configuration
+
+```typescript
+const kudos = new Kudos({
+  apiKey: 'kudo_live_xxx',      // Required: Your project API key
+  baseUrl: 'https://api.kudosapi.com', // Optional: API base URL
+  timeout: 5000,                // Optional: Request timeout in ms (default: 5000)
+  debug: false                  // Optional: Enable debug logging
+});
+```
+
+## Methods
+
+### `track(event, options?)`
+
+Send a custom event.
+
+```typescript
+await kudos.track({
+  type: 'sale',           // Required: Event type
+  title: 'New sale!',     // Optional: Human-readable title
+  value: 49.00,           // Optional: Numeric value
+  currency: 'USD',        // Optional: ISO currency code
+  data: { ... }           // Optional: Additional data
+});
+```
+
+Options:
+- `fireAndForget`: Set to `true` to return immediately without waiting for a response.
+
+### `sale(amount, currency, data?)`
+
+Convenience method for tracking sales.
+
+```typescript
+await kudos.sale(99.00, 'USD', { customer: 'jane@example.com' });
+```
+
+### `signup(data?)`
+
+Convenience method for tracking signups.
+
+```typescript
+await kudos.signup({ source: 'landing_page' });
+```
+
+### `milestone(title, value?, data?)`
+
+Convenience method for tracking milestones.
+
+```typescript
+await kudos.milestone('100 customers!', 100);
+```
+
+## Fire and Forget
+
+For non-blocking event tracking, use fire-and-forget mode:
+
+```typescript
+// Returns immediately, doesn't wait for response
+kudos.track({ type: 'pageview' }, { fireAndForget: true });
+```
+
+## Error Handling
+
+The SDK handles errors gracefully and returns structured error responses:
+
+```typescript
+const result = await kudos.track({ type: 'sale' });
+
+if (!result.success) {
+  console.error(result.error); // Error message
+  console.error(result.code);  // Error code (e.g., 'INVALID_API_KEY')
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `MISSING_API_KEY` | No API key provided |
+| `INVALID_API_KEY` | API key is invalid |
+| `INVALID_PAYLOAD` | Request body is malformed |
+| `PAYLOAD_TOO_LARGE` | Request exceeds 100KB limit |
+| `RATE_LIMITED` | Too many requests |
+| `INTERNAL_ERROR` | Server error |
+| `TIMEOUT` | Request timed out |
+| `NETWORK_ERROR` | Network connection failed |
+
+## TypeScript
+
+Full TypeScript support is included:
+
+```typescript
+import { Kudos, TrackEventData, TrackResponse } from '@kudosapi/sdk';
+
+const event: TrackEventData = {
+  type: 'sale',
+  value: 99,
+  currency: 'USD'
+};
+
+const result: TrackResponse = await kudos.track(event);
+```
+
+## Publishing (Maintainers)
+
+To publish a new version to npm:
+
+1. **Update version** in `packages/sdk/package.json`
+2. **Run the deploy script** from the repo root:
+   ```bash
+   ./scripts/deploy-sdk-npm.sh
+   ```
+3. **When prompted**, enter your npm 2FA code (from your authenticator app):
+   ```bash
+   cd packages/sdk && npm publish --access public --otp=YOUR_6_DIGIT_CODE
+   cd ../.. && git checkout dev
+   ```
+
+The deploy script will checkout `master`, run tests, build, and prompt for publish confirmation.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+/**
+ * Configuration options for the KudosAPI client
+ */
+interface KudosConfig {
+    /** Your KudosAPI API key */
+    apiKey: string;
+    /** Custom API base URL (defaults to https://api.kudosapi.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (defaults to 5000) */
+    timeout?: number;
+    /** Enable debug logging (defaults to false) */
+    debug?: boolean;
+}
+/**
+ * Event data to track
+ */
+interface TrackEventData {
+    /** Event type identifier (e.g., "sale", "signup", "milestone") */
+    type: string;
+    /** Optional human-readable title for display */
+    title?: string;
+    /** Optional numeric value (e.g., sale amount) */
+    value?: number;
+    /** Optional ISO currency code if value is monetary (e.g., "USD") */
+    currency?: string;
+    /** Optional additional event data */
+    data?: Record<string, unknown>;
+    /** Optional timestamp override (ISO 8601 format) */
+    timestamp?: string;
+}
+/**
+ * Successful response from the API
+ */
+interface TrackSuccessResponse {
+    success: true;
+    eventId: string;
+}
+/**
+ * Error response from the API
+ */
+interface TrackErrorResponse {
+    success: false;
+    error: string;
+    code: string;
+}
+/**
+ * Response from the track method
+ */
+type TrackResponse = TrackSuccessResponse | TrackErrorResponse;
+/**
+ * Options for the track method
+ */
+interface TrackOptions {
+    /** If true, don't wait for response (fire and forget) */
+    fireAndForget?: boolean;
+}
+
+/**
+ * KudosAPI Client
+ *
+ * @example
+ * ```ts
+ * import { Kudos } from '@kudosapi/sdk';
+ *
+ * const kudos = new Kudos({ apiKey: 'kudo_live_xxx' });
+ *
+ * // Track an event
+ * await kudos.track({
+ *   type: 'sale',
+ *   title: 'New Pro subscription',
+ *   value: 99,
+ *   currency: 'USD',
+ *   data: { customer: 'john@example.com' }
+ * });
+ * ```
+ */
+declare class Kudos {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private debug;
+    constructor(config: KudosConfig);
+    /**
+     * Track an event
+     *
+     * @param event - The event data to track
+     * @param options - Optional tracking options
+     * @returns Promise with the API response (unless fireAndForget is true)
+     */
+    track(event: TrackEventData, options?: TrackOptions): Promise<TrackResponse | void>;
+    /**
+     * Convenience method to track a sale
+     */
+    sale(amount: number, currency: string, data?: Record<string, unknown>): Promise<TrackResponse | void>;
+    /**
+     * Convenience method to track a signup
+     */
+    signup(data?: Record<string, unknown>): Promise<TrackResponse | void>;
+    /**
+     * Convenience method to track a milestone
+     */
+    milestone(title: string, value?: number, data?: Record<string, unknown>): Promise<TrackResponse | void>;
+}
+
+export { Kudos, type KudosConfig, type TrackErrorResponse, type TrackEventData, type TrackOptions, type TrackResponse, type TrackSuccessResponse };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Configuration options for the KudosAPI client
+ */
+interface KudosConfig {
+    /** Your KudosAPI API key */
+    apiKey: string;
+    /** Custom API base URL (defaults to https://api.kudosapi.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (defaults to 5000) */
+    timeout?: number;
+    /** Enable debug logging (defaults to false) */
+    debug?: boolean;
+}
+/**
+ * Event data to track
+ */
+interface TrackEventData {
+    /** Event type identifier (e.g., "sale", "signup", "milestone") */
+    type: string;
+    /** Optional human-readable title for display */
+    title?: string;
+    /** Optional numeric value (e.g., sale amount) */
+    value?: number;
+    /** Optional ISO currency code if value is monetary (e.g., "USD") */
+    currency?: string;
+    /** Optional additional event data */
+    data?: Record<string, unknown>;
+    /** Optional timestamp override (ISO 8601 format) */
+    timestamp?: string;
+}
+/**
+ * Successful response from the API
+ */
+interface TrackSuccessResponse {
+    success: true;
+    eventId: string;
+}
+/**
+ * Error response from the API
+ */
+interface TrackErrorResponse {
+    success: false;
+    error: string;
+    code: string;
+}
+/**
+ * Response from the track method
+ */
+type TrackResponse = TrackSuccessResponse | TrackErrorResponse;
+/**
+ * Options for the track method
+ */
+interface TrackOptions {
+    /** If true, don't wait for response (fire and forget) */
+    fireAndForget?: boolean;
+}
+
+/**
+ * KudosAPI Client
+ *
+ * @example
+ * ```ts
+ * import { Kudos } from '@kudosapi/sdk';
+ *
+ * const kudos = new Kudos({ apiKey: 'kudo_live_xxx' });
+ *
+ * // Track an event
+ * await kudos.track({
+ *   type: 'sale',
+ *   title: 'New Pro subscription',
+ *   value: 99,
+ *   currency: 'USD',
+ *   data: { customer: 'john@example.com' }
+ * });
+ * ```
+ */
+declare class Kudos {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private debug;
+    constructor(config: KudosConfig);
+    /**
+     * Track an event
+     *
+     * @param event - The event data to track
+     * @param options - Optional tracking options
+     * @returns Promise with the API response (unless fireAndForget is true)
+     */
+    track(event: TrackEventData, options?: TrackOptions): Promise<TrackResponse | void>;
+    /**
+     * Convenience method to track a sale
+     */
+    sale(amount: number, currency: string, data?: Record<string, unknown>): Promise<TrackResponse | void>;
+    /**
+     * Convenience method to track a signup
+     */
+    signup(data?: Record<string, unknown>): Promise<TrackResponse | void>;
+    /**
+     * Convenience method to track a milestone
+     */
+    milestone(title: string, value?: number, data?: Record<string, unknown>): Promise<TrackResponse | void>;
+}
+
+export { Kudos, type KudosConfig, type TrackErrorResponse, type TrackEventData, type TrackOptions, type TrackResponse, type TrackSuccessResponse };

package/dist/index.js

@@ -0,0 +1,155 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Kudos: () => Kudos
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.kudosapi.com";
+var DEFAULT_TIMEOUT = 5e3;
+var MAX_PAYLOAD_SIZE = 100 * 1024;
+var Kudos = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("KudosAPI: apiKey is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.debug = config.debug || false;
+    if (typeof process !== "undefined" && process.env?.NODE_ENV === "production" && config.apiKey.startsWith("kudo_test_")) {
+      console.warn(
+        "[KudosAPI] Warning: Using a test API key in production. Events will not be processed."
+      );
+    }
+  }
+  /**
+   * Track an event
+   *
+   * @param event - The event data to track
+   * @param options - Optional tracking options
+   * @returns Promise with the API response (unless fireAndForget is true)
+   */
+  async track(event, options) {
+    const { fireAndForget = false } = options || {};
+    const url = `${this.baseUrl}/api/events`;
+    const body = JSON.stringify(event);
+    const payloadSize = new TextEncoder().encode(body).length;
+    if (payloadSize > MAX_PAYLOAD_SIZE) {
+      const error = `Payload too large (${Math.round(payloadSize / 1024)}KB). Maximum size is 100KB.`;
+      if (this.debug) {
+        console.error("[KudosAPI]", error);
+      }
+      if (fireAndForget) return;
+      return {
+        success: false,
+        error,
+        code: "PAYLOAD_TOO_LARGE"
+      };
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      if (this.debug) {
+        console.log("[KudosAPI] Tracking event:", event);
+        console.log("[KudosAPI] Note: Ensure event data does not contain sensitive PII.");
+      }
+      const fetchPromise = fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body,
+        signal: controller.signal
+      });
+      if (fireAndForget) {
+        fetchPromise.catch((error) => {
+          if (this.debug) {
+            console.error("[KudosAPI] Fire-and-forget error:", error);
+          }
+        });
+        return;
+      }
+      const response = await fetchPromise;
+      const data = await response.json();
+      if (this.debug) {
+        console.log("[KudosAPI] Response:", data);
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        return {
+          success: false,
+          error: "Request timed out",
+          code: "TIMEOUT"
+        };
+      }
+      if (this.debug) {
+        console.error("[KudosAPI] Error:", error);
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+        code: "NETWORK_ERROR"
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Convenience method to track a sale
+   */
+  async sale(amount, currency, data) {
+    return this.track({
+      type: "sale",
+      value: amount,
+      currency,
+      data
+    });
+  }
+  /**
+   * Convenience method to track a signup
+   */
+  async signup(data) {
+    return this.track({
+      type: "signup",
+      data
+    });
+  }
+  /**
+   * Convenience method to track a milestone
+   */
+  async milestone(title, value, data) {
+    return this.track({
+      type: "milestone",
+      title,
+      value,
+      data
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Kudos
+});

package/dist/index.mjs

@@ -0,0 +1,128 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.kudosapi.com";
+var DEFAULT_TIMEOUT = 5e3;
+var MAX_PAYLOAD_SIZE = 100 * 1024;
+var Kudos = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("KudosAPI: apiKey is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.debug = config.debug || false;
+    if (typeof process !== "undefined" && process.env?.NODE_ENV === "production" && config.apiKey.startsWith("kudo_test_")) {
+      console.warn(
+        "[KudosAPI] Warning: Using a test API key in production. Events will not be processed."
+      );
+    }
+  }
+  /**
+   * Track an event
+   *
+   * @param event - The event data to track
+   * @param options - Optional tracking options
+   * @returns Promise with the API response (unless fireAndForget is true)
+   */
+  async track(event, options) {
+    const { fireAndForget = false } = options || {};
+    const url = `${this.baseUrl}/api/events`;
+    const body = JSON.stringify(event);
+    const payloadSize = new TextEncoder().encode(body).length;
+    if (payloadSize > MAX_PAYLOAD_SIZE) {
+      const error = `Payload too large (${Math.round(payloadSize / 1024)}KB). Maximum size is 100KB.`;
+      if (this.debug) {
+        console.error("[KudosAPI]", error);
+      }
+      if (fireAndForget) return;
+      return {
+        success: false,
+        error,
+        code: "PAYLOAD_TOO_LARGE"
+      };
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      if (this.debug) {
+        console.log("[KudosAPI] Tracking event:", event);
+        console.log("[KudosAPI] Note: Ensure event data does not contain sensitive PII.");
+      }
+      const fetchPromise = fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body,
+        signal: controller.signal
+      });
+      if (fireAndForget) {
+        fetchPromise.catch((error) => {
+          if (this.debug) {
+            console.error("[KudosAPI] Fire-and-forget error:", error);
+          }
+        });
+        return;
+      }
+      const response = await fetchPromise;
+      const data = await response.json();
+      if (this.debug) {
+        console.log("[KudosAPI] Response:", data);
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        return {
+          success: false,
+          error: "Request timed out",
+          code: "TIMEOUT"
+        };
+      }
+      if (this.debug) {
+        console.error("[KudosAPI] Error:", error);
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+        code: "NETWORK_ERROR"
+      };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Convenience method to track a sale
+   */
+  async sale(amount, currency, data) {
+    return this.track({
+      type: "sale",
+      value: amount,
+      currency,
+      data
+    });
+  }
+  /**
+   * Convenience method to track a signup
+   */
+  async signup(data) {
+    return this.track({
+      type: "signup",
+      data
+    });
+  }
+  /**
+   * Convenience method to track a milestone
+   */
+  async milestone(title, value, data) {
+    return this.track({
+      type: "milestone",
+      title,
+      value,
+      data
+    });
+  }
+};
+export {
+  Kudos
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kudosapi/sdk",
+  "version": "0.1.1",
+  "description": "Official SDK for KudosAPI - Get positive notifications when good things happen in your app",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "kudos",
+    "kudosapi",
+    "notifications",
+    "positive",
+    "events",
+    "analytics",
+    "saas",
+    "indie-hacker",
+    "motivation",
+    "dopamine"
+  ],
+  "author": "KudosAPI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kudosapi/sdk"
+  },
+  "homepage": "https://kudosapi.com",
+  "bugs": {
+    "url": "https://github.com/kudosapi/sdk/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}