@simple-product/sdk 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# @simple-product/sdk
+
+Track users and product usage with Simple Product.
+
+## Installation
+
+```bash
+npm install @simple-product/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SimpleProduct } from '@simple-product/sdk';
+
+// Initialize once in your app
+const sp = new SimpleProduct({
+  apiKey: 'sk_your_api_key',
+});
+
+// Identify users when they sign in
+sp.identify({
+  userId: user.id,
+  email: user.email,
+  name: user.name,
+  company: user.company,
+});
+
+// That's it! Analytics are now tracked automatically.
+```
+
+## How It Works
+
+The SDK automatically sends a **heartbeat event once per day** per user. This single event powers:
+
+- **DAU/WAU/MAU** - Daily, weekly, monthly active users
+- **Retention** - Cohort retention analysis
+- **Stickiness** - DAU/MAU engagement ratio
+
+No configuration needed. Just identify your users and analytics happen automatically.
+
+## API Reference
+
+### `new SimpleProduct(config)`
+
+Create a new SDK instance.
+
+```typescript
+const sp = new SimpleProduct({
+  apiKey: 'sk_your_api_key',        // Required
+  endpoint: 'https://...',           // Optional, defaults to production
+  disableAutoHeartbeat: false,       // Optional, disable auto-tracking
+  debug: false,                      // Optional, enable console logging
+});
+```
+
+### `sp.identify(params)`
+
+Identify a user. Call this when a user signs in.
+
+```typescript
+sp.identify({
+  userId: 'user_123',          // Required - your internal user ID
+  email: 'user@example.com',   // Optional
+  name: 'Jane Doe',            // Optional
+  company: 'Acme Inc',         // Optional
+  traits: {                    // Optional - any additional data
+    plan: 'pro',
+    role: 'admin',
+  },
+});
+```
+
+### `sp.track(event, properties?)`
+
+Track a custom event.
+
+```typescript
+sp.track('feature_used', {
+  feature: 'export_report',
+  format: 'csv',
+});
+```
+
+### `sp.reset()`
+
+Reset the user. Call this when a user signs out.
+
+```typescript
+sp.reset();
+```
+
+### `sp.destroy()`
+
+Clean up SDK resources. Call this if you need to remove the SDK.
+
+```typescript
+sp.destroy();
+```
+
+## React Integration (Recommended)
+
+The easiest way to integrate is with our React provider:
+
+```tsx
+// app/providers.tsx
+'use client';
+
+import { SimpleProductProvider } from '@simple-product/sdk/react';
+
+export function Providers({ children, user }) {
+  return (
+    <SimpleProductProvider
+      apiKey={process.env.NEXT_PUBLIC_SP_API_KEY!}
+      user={user ? {
+        id: user.id,
+        email: user.email,
+        name: user.name,
+      } : null}
+    >
+      {children}
+    </SimpleProductProvider>
+  );
+}
+```
+
+The provider automatically:
+- Calls `identify()` when user changes
+- Sends heartbeats once per day
+- Resets on logout
+
+### Track Custom Events
+
+```tsx
+import { useSimpleProduct } from '@simple-product/sdk/react';
+
+function MyComponent() {
+  const { track } = useSimpleProduct();
+
+  return (
+    <button onClick={() => track('button_clicked', { button: 'signup' })}>
+      Sign Up
+    </button>
+  );
+}
+```
+
+## Manual Setup
+
+If you're not using React, you can use the SDK directly:
+
+```tsx
+import { SimpleProduct } from '@simple-product/sdk';
+
+const sp = new SimpleProduct({
+  apiKey: process.env.NEXT_PUBLIC_SP_API_KEY!,
+});
+
+// When user logs in
+sp.identify({
+  userId: user.id,
+  email: user.email,
+  name: user.name,
+});
+
+// Track custom events
+sp.track('feature_used', { feature: 'export' });
+
+// On logout
+sp.reset();
+```
+
+## License
+
+MIT

package/dist/chunk-7F2GKQLH.mjs

@@ -0,0 +1,216 @@
+// src/index.ts
+var STORAGE_KEY_PREFIX = "sp_sdk_";
+var HEARTBEAT_STORAGE_KEY = `${STORAGE_KEY_PREFIX}last_heartbeat`;
+var USER_ID_STORAGE_KEY = `${STORAGE_KEY_PREFIX}user_id`;
+var ANONYMOUS_ID_STORAGE_KEY = `${STORAGE_KEY_PREFIX}anonymous_id`;
+var SimpleProduct = class {
+  constructor(config) {
+    this.userId = null;
+    this.heartbeatInterval = null;
+    this.visibilityHandler = null;
+    this.apiKey = config.apiKey;
+    this.endpoint = config.endpoint || "https://simpleproduct.io/api/v1";
+    this.debug = config.debug || false;
+    this.disableAutoHeartbeat = config.disableAutoHeartbeat || false;
+    this.anonymousId = this.getOrCreateAnonymousId();
+    this.userId = this.getStoredUserId();
+    if (!this.disableAutoHeartbeat && typeof window !== "undefined") {
+      this.startHeartbeat();
+    }
+    this.log("Initialized", { userId: this.userId, anonymousId: this.anonymousId });
+  }
+  /**
+   * Identify a user - call this when a user signs in
+   */
+  identify(params) {
+    this.userId = params.userId;
+    this.storeUserId(params.userId);
+    this.log("Identify", params);
+    this.sendRequest("/people", {
+      method: "POST",
+      body: {
+        externalId: params.userId,
+        email: params.email,
+        name: params.name,
+        company: params.company,
+        ...params.traits
+      }
+    }).catch((err) => this.log("Identify error", err));
+    this.sendHeartbeat();
+  }
+  track(eventOrParams, properties) {
+    const event = typeof eventOrParams === "string" ? eventOrParams : eventOrParams.event;
+    const props = typeof eventOrParams === "string" ? properties : eventOrParams.properties;
+    this.log("Track", { event, properties: props });
+    this.sendRequest("/events", {
+      method: "POST",
+      body: {
+        event,
+        userId: this.userId,
+        anonymousId: this.anonymousId,
+        properties: props,
+        context: this.getContext()
+      }
+    }).catch((err) => this.log("Track error", err));
+  }
+  /**
+   * Reset the user - call this when a user signs out
+   */
+  reset() {
+    this.userId = null;
+    this.clearStoredUserId();
+    this.anonymousId = this.generateAnonymousId();
+    this.storeAnonymousId(this.anonymousId);
+    this.log("Reset");
+  }
+  /**
+   * Manually send a heartbeat (usually not needed - happens automatically)
+   */
+  heartbeat() {
+    this.sendHeartbeat();
+  }
+  /**
+   * Clean up SDK resources
+   */
+  destroy() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    this.log("Destroyed");
+  }
+  // --- Private methods ---
+  startHeartbeat() {
+    this.sendHeartbeatIfNeeded();
+    this.heartbeatInterval = setInterval(() => {
+      this.sendHeartbeatIfNeeded();
+    }, 5 * 60 * 1e3);
+    this.visibilityHandler = () => {
+      if (document.visibilityState === "visible") {
+        this.sendHeartbeatIfNeeded();
+      }
+    };
+    document.addEventListener("visibilitychange", this.visibilityHandler);
+  }
+  sendHeartbeatIfNeeded() {
+    if (!this.userId) {
+      this.log("Skipping heartbeat - no user identified");
+      return;
+    }
+    const today = this.getTodayString();
+    const lastHeartbeat = this.getLastHeartbeatDate();
+    if (lastHeartbeat === today) {
+      this.log("Skipping heartbeat - already sent today");
+      return;
+    }
+    this.sendHeartbeat();
+  }
+  sendHeartbeat() {
+    if (!this.userId) {
+      this.log("Cannot send heartbeat - no user identified");
+      return;
+    }
+    const today = this.getTodayString();
+    this.log("Sending heartbeat");
+    this.sendRequest("/events", {
+      method: "POST",
+      body: {
+        event: "sp_heartbeat",
+        userId: this.userId,
+        anonymousId: this.anonymousId,
+        context: this.getContext()
+      }
+    }).then(() => {
+      this.storeLastHeartbeatDate(today);
+      this.log("Heartbeat sent successfully");
+    }).catch((err) => this.log("Heartbeat error", err));
+  }
+  async sendRequest(path, options) {
+    const url = `${this.endpoint}${path}`;
+    const response = await fetch(url, {
+      method: options.method,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: options.body ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`API error: ${response.status} ${error}`);
+    }
+    return response.json();
+  }
+  getContext() {
+    if (typeof window === "undefined") {
+      return {};
+    }
+    return {
+      userAgent: navigator.userAgent,
+      page: {
+        url: window.location.href,
+        title: document.title,
+        referrer: document.referrer
+      }
+    };
+  }
+  getTodayString() {
+    return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  }
+  getLastHeartbeatDate() {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage.getItem(HEARTBEAT_STORAGE_KEY);
+  }
+  storeLastHeartbeatDate(date) {
+    if (typeof localStorage === "undefined") return;
+    localStorage.setItem(HEARTBEAT_STORAGE_KEY, date);
+  }
+  getStoredUserId() {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage.getItem(USER_ID_STORAGE_KEY);
+  }
+  storeUserId(userId) {
+    if (typeof localStorage === "undefined") return;
+    localStorage.setItem(USER_ID_STORAGE_KEY, userId);
+  }
+  clearStoredUserId() {
+    if (typeof localStorage === "undefined") return;
+    localStorage.removeItem(USER_ID_STORAGE_KEY);
+    localStorage.removeItem(HEARTBEAT_STORAGE_KEY);
+  }
+  getOrCreateAnonymousId() {
+    if (typeof localStorage === "undefined") {
+      return this.generateAnonymousId();
+    }
+    const stored = localStorage.getItem(ANONYMOUS_ID_STORAGE_KEY);
+    if (stored) return stored;
+    const id = this.generateAnonymousId();
+    this.storeAnonymousId(id);
+    return id;
+  }
+  storeAnonymousId(id) {
+    if (typeof localStorage === "undefined") return;
+    localStorage.setItem(ANONYMOUS_ID_STORAGE_KEY, id);
+  }
+  generateAnonymousId() {
+    return "anon_" + Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+  }
+  log(message, data) {
+    if (!this.debug) return;
+    console.log(`[SimpleProduct] ${message}`, data !== void 0 ? data : "");
+  }
+};
+function createSimpleProduct(config) {
+  return new SimpleProduct(config);
+}
+var index_default = SimpleProduct;
+
+export {
+  SimpleProduct,
+  createSimpleProduct,
+  index_default
+};

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+/**
+ * Simple Product SDK
+ *
+ * Track users and product usage with minimal setup.
+ * Automatically sends heartbeat events (once per day) to power analytics.
+ */
+interface SimpleProductConfig {
+    /** Your API key (starts with sk_) */
+    apiKey: string;
+    /** API endpoint (defaults to https://simpleproduct.io/api/v1) */
+    endpoint?: string;
+    /** Disable automatic heartbeat tracking (default: false) */
+    disableAutoHeartbeat?: boolean;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface IdentifyParams {
+    /** Unique user ID from your system */
+    userId: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** Company/organization name */
+    company?: string;
+    /** Any additional traits */
+    traits?: Record<string, unknown>;
+}
+interface TrackParams {
+    /** Event name (e.g., "feature_used", "button_clicked") */
+    event: string;
+    /** Event properties */
+    properties?: Record<string, unknown>;
+}
+declare class SimpleProduct {
+    private apiKey;
+    private endpoint;
+    private debug;
+    private userId;
+    private anonymousId;
+    private disableAutoHeartbeat;
+    private heartbeatInterval;
+    private visibilityHandler;
+    constructor(config: SimpleProductConfig);
+    /**
+     * Identify a user - call this when a user signs in
+     */
+    identify(params: IdentifyParams): void;
+    /**
+     * Track a custom event
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
+    track(params: TrackParams): void;
+    /**
+     * Reset the user - call this when a user signs out
+     */
+    reset(): void;
+    /**
+     * Manually send a heartbeat (usually not needed - happens automatically)
+     */
+    heartbeat(): void;
+    /**
+     * Clean up SDK resources
+     */
+    destroy(): void;
+    private startHeartbeat;
+    private sendHeartbeatIfNeeded;
+    private sendHeartbeat;
+    private sendRequest;
+    private getContext;
+    private getTodayString;
+    private getLastHeartbeatDate;
+    private storeLastHeartbeatDate;
+    private getStoredUserId;
+    private storeUserId;
+    private clearStoredUserId;
+    private getOrCreateAnonymousId;
+    private storeAnonymousId;
+    private generateAnonymousId;
+    private log;
+}
+
+declare function createSimpleProduct(config: SimpleProductConfig): SimpleProduct;
+
+export { type IdentifyParams, SimpleProduct, type SimpleProductConfig, type TrackParams, createSimpleProduct, SimpleProduct as default };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Simple Product SDK
+ *
+ * Track users and product usage with minimal setup.
+ * Automatically sends heartbeat events (once per day) to power analytics.
+ */
+interface SimpleProductConfig {
+    /** Your API key (starts with sk_) */
+    apiKey: string;
+    /** API endpoint (defaults to https://simpleproduct.io/api/v1) */
+    endpoint?: string;
+    /** Disable automatic heartbeat tracking (default: false) */
+    disableAutoHeartbeat?: boolean;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface IdentifyParams {
+    /** Unique user ID from your system */
+    userId: string;
+    /** User's email address */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** Company/organization name */
+    company?: string;
+    /** Any additional traits */
+    traits?: Record<string, unknown>;
+}
+interface TrackParams {
+    /** Event name (e.g., "feature_used", "button_clicked") */
+    event: string;
+    /** Event properties */
+    properties?: Record<string, unknown>;
+}
+declare class SimpleProduct {
+    private apiKey;
+    private endpoint;
+    private debug;
+    private userId;
+    private anonymousId;
+    private disableAutoHeartbeat;
+    private heartbeatInterval;
+    private visibilityHandler;
+    constructor(config: SimpleProductConfig);
+    /**
+     * Identify a user - call this when a user signs in
+     */
+    identify(params: IdentifyParams): void;
+    /**
+     * Track a custom event
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
+    track(params: TrackParams): void;
+    /**
+     * Reset the user - call this when a user signs out
+     */
+    reset(): void;
+    /**
+     * Manually send a heartbeat (usually not needed - happens automatically)
+     */
+    heartbeat(): void;
+    /**
+     * Clean up SDK resources
+     */
+    destroy(): void;
+    private startHeartbeat;
+    private sendHeartbeatIfNeeded;
+    private sendHeartbeat;
+    private sendRequest;
+    private getContext;
+    private getTodayString;
+    private getLastHeartbeatDate;
+    private storeLastHeartbeatDate;
+    private getStoredUserId;
+    private storeUserId;
+    private clearStoredUserId;
+    private getOrCreateAnonymousId;
+    private storeAnonymousId;
+    private generateAnonymousId;
+    private log;
+}
+
+declare function createSimpleProduct(config: SimpleProductConfig): SimpleProduct;
+
+export { type IdentifyParams, SimpleProduct, type SimpleProductConfig, type TrackParams, createSimpleProduct, SimpleProduct as default };