userplex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Userplex
+
+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,319 @@
+# Userplex
+
+Dead simple analytics SDK. No complex setup. Just track.
+
+## Installation
+
+```bash
+npm install userplex
+```
+
+## Usage
+
+```javascript
+import Userplex from 'userplex';
+
+// Initialize with your API key
+const userplex = new Userplex('upx_your_api_key_here');
+
+// Track events
+await userplex.track('user123', 'button_clicked', {
+  button: 'signup',
+  page: '/pricing'
+});
+
+// Identify users
+await userplex.identify('user123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'premium'
+});
+
+// Log LLM conversations
+await userplex.logConversation({
+  userId: 'user123',
+  messages: [
+    { role: 'user', content: 'How do I reset my password?' },
+    { role: 'assistant', content: 'Click on "Forgot Password" on the login page.' }
+  ]
+});
+```
+
+That's it. No route setup. No configuration files. Just analytics.
+
+## API
+
+### `new Userplex(apiKey, options?)`
+
+Create a new Userplex instance.
+
+- `apiKey` - Your Userplex API key (required)
+- `options` - Optional configuration
+  - `baseUrl` - Your Userplex server URL (default: `http://localhost:3000`)
+  - `timeout` - Request timeout in ms (default: `10000`)
+  - `debug` - Enable debug logging (default: `false`)
+
+```javascript
+const userplex = new Userplex('upx_key', {
+  baseUrl: 'https://analytics.myapp.com',
+  timeout: 30000,
+  debug: true
+});
+```
+
+### `track(userId, event, properties?)`
+
+Track an event.
+
+```javascript
+await userplex.track('user123', 'purchase_completed', {
+  amount: 99.99,
+  currency: 'USD',
+  items: ['product1', 'product2']
+});
+```
+
+### `identify(userId, properties?)`
+
+Identify a user and set their properties.
+
+```javascript
+await userplex.identify('user123', {
+  email: 'john@example.com',
+  company: 'Acme Corp',
+  role: 'admin',
+  plan: 'enterprise'
+});
+```
+
+### `logConversation(options)`
+
+Log an LLM conversation for observability.
+
+```javascript
+await userplex.logConversation({
+  userId: 'user123',                    // optional
+  conversationId: 'conv_abc',           // optional
+  conversationName: 'Support Chat',     // optional
+  messages: [                          // required
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Hello!' },
+    { role: 'assistant', content: 'Hi! How can I help?' }
+  ]
+});
+```
+
+### `trackBatch(events)`
+
+Track multiple events at once.
+
+```javascript
+await userplex.trackBatch([
+  { userId: 'user1', event: 'login', properties: { method: 'google' } },
+  { userId: 'user2', event: 'signup', properties: { plan: 'free' } },
+  { userId: 'user3', event: 'upgrade', properties: { plan: 'pro' } }
+]);
+```
+
+## Using in Different Environments
+
+### Node.js / Server-side
+
+Use it directly with your API key:
+
+```javascript
+// server.js
+import Userplex from 'userplex';
+
+const userplex = new Userplex(process.env.USERPLEX_API_KEY);
+
+app.post('/api/checkout', async (req, res) => {
+  // Process payment...
+  
+  // Track purchase
+  await userplex.track(req.user.id, 'purchase_completed', {
+    amount: req.body.amount
+  });
+  
+  res.json({ success: true });
+});
+```
+
+### Next.js API Routes
+
+```javascript
+// app/api/checkout/route.js
+import Userplex from 'userplex';
+
+const userplex = new Userplex(process.env.USERPLEX_API_KEY);
+
+export async function POST(request) {
+  const body = await request.json();
+  
+  await userplex.track(body.userId, 'purchase_completed', {
+    amount: body.amount
+  });
+  
+  return Response.json({ success: true });
+}
+```
+
+### Client-side (Browser)
+
+⚠️ **Never put your API key in client-side code!** 
+
+For client-side tracking, you have two options:
+
+#### Option 1: Create a simple API endpoint
+
+```javascript
+// app/api/track/route.js (Next.js example)
+import Userplex from 'userplex';
+
+const userplex = new Userplex(process.env.USERPLEX_API_KEY);
+
+export async function POST(request) {
+  const { userId, event, properties } = await request.json();
+  await userplex.track(userId, event, properties);
+  return Response.json({ success: true });
+}
+```
+
+Then in your client:
+
+```javascript
+// In your React component
+async function trackEvent(event, properties) {
+  await fetch('/api/track', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      userId: currentUser.id,
+      event,
+      properties
+    })
+  });
+}
+
+// Use it
+trackEvent('button_clicked', { button: 'signup' });
+```
+
+#### Option 2: Use environment-specific initialization
+
+```javascript
+// lib/analytics.js
+import Userplex from 'userplex';
+
+// Server-side: use real instance
+// Client-side: use a proxy that calls your API
+const userplex = typeof window === 'undefined' 
+  ? new Userplex(process.env.USERPLEX_API_KEY)
+  : {
+      track: async (userId, event, properties) => {
+        await fetch('/api/track', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ userId, event, properties })
+        });
+      },
+      identify: async (userId, properties) => {
+        await fetch('/api/identify', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ userId, properties })
+        });
+      }
+    };
+
+export default userplex;
+```
+
+## Error Handling
+
+```javascript
+try {
+  await userplex.track('user123', 'event');
+} catch (error) {
+  if (error.name === 'UserplexError') {
+    console.error('Analytics error:', error.message);
+    console.error('Status code:', error.statusCode);
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support included:
+
+```typescript
+import Userplex, { ConversationMessage, UserplexError } from 'userplex';
+
+const userplex = new Userplex('upx_key');
+
+const messages: ConversationMessage[] = [
+  { role: 'user', content: 'Hello' },
+  { role: 'assistant', content: 'Hi!' }
+];
+
+try {
+  await userplex.logConversation({ messages });
+} catch (error) {
+  if (error instanceof UserplexError) {
+    // Typed error handling
+  }
+}
+```
+
+## Examples
+
+### E-commerce Tracking
+
+```javascript
+// Track the full customer journey
+await userplex.track(userId, 'product_viewed', { productId, price });
+await userplex.track(userId, 'add_to_cart', { productId, quantity });
+await userplex.track(userId, 'checkout_started', { cartValue });
+await userplex.track(userId, 'purchase_completed', { orderId, amount });
+```
+
+### SaaS Application
+
+```javascript
+// Track feature usage
+await userplex.track(userId, 'feature_used', {
+  feature: 'csv_export',
+  recordCount: 1000
+});
+
+// Track subscription changes
+await userplex.identify(userId, {
+  plan: 'enterprise',
+  mrr: 499
+});
+```
+
+### AI Application
+
+```javascript
+// Log every conversation for debugging and analytics
+const messages = [];
+
+// User asks a question
+messages.push({ role: 'user', content: userInput });
+
+// Get AI response
+const response = await callOpenAI(messages);
+messages.push({ role: 'assistant', content: response });
+
+// Log to Userplex
+await userplex.logConversation({
+  userId: currentUser.id,
+  conversationName: 'Chat Session',
+  messages
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+/**
+ * Userplex - Simple Analytics SDK
+ *
+ * Just install and use. No complex setup required.
+ *
+ * @example
+ * ```ts
+ * import Userplex from 'userplex';
+ *
+ * const userplex = new Userplex('upx_your_api_key');
+ *
+ * // Track events
+ * await userplex.track('user123', 'button_clicked', { button: 'signup' });
+ *
+ * // Identify users
+ * await userplex.identify('user123', { email: 'user@example.com' });
+ *
+ * // Log conversations
+ * await userplex.logConversation({
+ *   messages: [
+ *     { role: 'user', content: 'Hello' },
+ *     { role: 'assistant', content: 'Hi there!' }
+ *   ]
+ * });
+ * ```
+ */
+interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface UserplexOptions {
+    /** Your Userplex instance URL (default: http://localhost:3000) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+declare class UserplexError extends Error {
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+declare class Userplex {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private debug;
+    constructor(apiKey: string, options?: UserplexOptions);
+    /**
+     * Track an event
+     */
+    track(userId: string, event: string, properties?: Record<string, any>): Promise<any>;
+    /**
+     * Identify a user
+     */
+    identify(externalId: string, properties?: Record<string, any>): Promise<any>;
+    /**
+     * Log a conversation
+     */
+    logConversation(options: {
+        messages: ConversationMessage[];
+        userId?: string;
+        conversationId?: string;
+        conversationName?: string;
+    }): Promise<any>;
+    /**
+     * Batch track multiple events
+     */
+    trackBatch(events: Array<{
+        userId: string;
+        event: string;
+        properties?: Record<string, any>;
+    }>): Promise<any[]>;
+    private request;
+}
+
+export { type ConversationMessage, Userplex, UserplexError, type UserplexOptions, Userplex as default };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Userplex - Simple Analytics SDK
+ *
+ * Just install and use. No complex setup required.
+ *
+ * @example
+ * ```ts
+ * import Userplex from 'userplex';
+ *
+ * const userplex = new Userplex('upx_your_api_key');
+ *
+ * // Track events
+ * await userplex.track('user123', 'button_clicked', { button: 'signup' });
+ *
+ * // Identify users
+ * await userplex.identify('user123', { email: 'user@example.com' });
+ *
+ * // Log conversations
+ * await userplex.logConversation({
+ *   messages: [
+ *     { role: 'user', content: 'Hello' },
+ *     { role: 'assistant', content: 'Hi there!' }
+ *   ]
+ * });
+ * ```
+ */
+interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+interface UserplexOptions {
+    /** Your Userplex instance URL (default: http://localhost:3000) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+declare class UserplexError extends Error {
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+declare class Userplex {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private debug;
+    constructor(apiKey: string, options?: UserplexOptions);
+    /**
+     * Track an event
+     */
+    track(userId: string, event: string, properties?: Record<string, any>): Promise<any>;
+    /**
+     * Identify a user
+     */
+    identify(externalId: string, properties?: Record<string, any>): Promise<any>;
+    /**
+     * Log a conversation
+     */
+    logConversation(options: {
+        messages: ConversationMessage[];
+        userId?: string;
+        conversationId?: string;
+        conversationName?: string;
+    }): Promise<any>;
+    /**
+     * Batch track multiple events
+     */
+    trackBatch(events: Array<{
+        userId: string;
+        event: string;
+        properties?: Record<string, any>;
+    }>): Promise<any[]>;
+    private request;
+}
+
+export { type ConversationMessage, Userplex, UserplexError, type UserplexOptions, Userplex as default };

package/dist/index.js

@@ -0,0 +1,132 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// index.ts
+var UserplexError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "UserplexError";
+  }
+};
+var Userplex = class {
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error("Userplex: API key is required");
+    }
+    if (!apiKey.startsWith("upx_")) {
+      throw new Error('Userplex: API key must start with "upx_"');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || "http://localhost:3000").replace(/\/$/, "");
+    this.timeout = options.timeout || 1e4;
+    this.debug = options.debug || false;
+  }
+  /**
+   * Track an event
+   */
+  async track(userId, event, properties) {
+    if (!userId || !event) {
+      throw new Error("userId and event are required");
+    }
+    return this.request("/api/events", {
+      userId,
+      event,
+      properties: properties || {}
+    });
+  }
+  /**
+   * Identify a user
+   */
+  async identify(externalId, properties) {
+    if (!externalId) {
+      throw new Error("externalId is required");
+    }
+    return this.request("/api/identify", {
+      externalId,
+      ...properties
+    }, {
+      "x-api-key": this.apiKey
+      // identify endpoint uses this header too
+    });
+  }
+  /**
+   * Log a conversation
+   */
+  async logConversation(options) {
+    if (!options.messages || options.messages.length === 0) {
+      throw new Error("messages array is required and cannot be empty");
+    }
+    return this.request("/api/conversations", {
+      externalUserId: options.userId,
+      conversationId: options.conversationId,
+      conversationName: options.conversationName,
+      messages: options.messages
+    });
+  }
+  /**
+   * Batch track multiple events
+   */
+  async trackBatch(events) {
+    if (!events || events.length === 0) {
+      throw new Error("events array is required and cannot be empty");
+    }
+    const promises = events.map((e) => this.track(e.userId, e.event, e.properties));
+    return Promise.all(promises);
+  }
+  async request(endpoint, data, additionalHeaders) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    if (this.debug) {
+      console.log(`[Userplex] POST ${url}`, JSON.stringify(data, null, 2));
+    }
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`,
+          ...additionalHeaders
+        },
+        body: JSON.stringify(data),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const responseData = await response.json();
+      if (this.debug) {
+        console.log(`[Userplex] Response:`, JSON.stringify(responseData, null, 2));
+      }
+      if (!response.ok) {
+        throw new UserplexError(
+          responseData.error || `Request failed with status ${response.status}`,
+          response.status,
+          responseData
+        );
+      }
+      return responseData;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new UserplexError("Request timeout", 408);
+      }
+      if (error instanceof UserplexError) {
+        throw error;
+      }
+      throw new UserplexError(
+        error.message || "An unexpected error occurred",
+        void 0,
+        error
+      );
+    }
+  }
+};
+var index_default = Userplex;
+
+exports.Userplex = Userplex;
+exports.UserplexError = UserplexError;
+exports.default = index_default;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Userplex - Simple Analytics SDK\n * \n * Just install and use. No complex setup required.\n * \n * @example\n * ```ts\n * import Userplex from 'userplex';\n * \n * const userplex = new Userplex('upx_your_api_key');\n * \n * // Track events\n * await userplex.track('user123', 'button_clicked', { button: 'signup' });\n * \n * // Identify users\n * await userplex.identify('user123', { email: 'user@example.com' });\n * \n * // Log conversations\n * await userplex.logConversation({\n *   messages: [\n *     { role: 'user', content: 'Hello' },\n *     { role: 'assistant', content: 'Hi there!' }\n *   ]\n * });\n * ```\n */\n\nexport interface ConversationMessage {\n  role: 'user' | 'assistant' | 'system';\n  content: string;\n}\n\nexport interface UserplexOptions {\n  /** Your Userplex instance URL (default: http://localhost:3000) */\n  baseUrl?: string;\n  /** Request timeout in ms (default: 10000) */\n  timeout?: number;\n  /** Enable debug logging (default: false) */\n  debug?: boolean;\n}\n\nexport class UserplexError extends Error {\n  constructor(\n    message: string,\n    public statusCode?: number,\n    public response?: any\n  ) {\n    super(message);\n    this.name = 'UserplexError';\n  }\n}\n\nclass Userplex {\n  private apiKey: string;\n  private baseUrl: string;\n  private timeout: number;\n  private debug: boolean;\n\n  constructor(apiKey: string, options: UserplexOptions = {}) {\n    if (!apiKey) {\n      throw new Error('Userplex: API key is required');\n    }\n    if (!apiKey.startsWith('upx_')) {\n      throw new Error('Userplex: API key must start with \"upx_\"');\n    }\n\n    this.apiKey = apiKey;\n    this.baseUrl = (options.baseUrl || 'http://localhost:3000').replace(/\\/$/, '');\n    this.timeout = options.timeout || 10000;\n    this.debug = options.debug || false;\n  }\n\n  /**\n   * Track an event\n   */\n  async track(userId: string, event: string, properties?: Record<string, any>) {\n    if (!userId || !event) {\n      throw new Error('userId and event are required');\n    }\n\n    return this.request('/api/events', {\n      userId,\n      event,\n      properties: properties || {}\n    });\n  }\n\n  /**\n   * Identify a user\n   */\n  async identify(externalId: string, properties?: Record<string, any>) {\n    if (!externalId) {\n      throw new Error('externalId is required');\n    }\n\n    return this.request('/api/identify', {\n      externalId,\n      ...properties\n    }, {\n      'x-api-key': this.apiKey // identify endpoint uses this header too\n    });\n  }\n\n  /**\n   * Log a conversation\n   */\n  async logConversation(options: {\n    messages: ConversationMessage[];\n    userId?: string;\n    conversationId?: string;\n    conversationName?: string;\n  }) {\n    if (!options.messages || options.messages.length === 0) {\n      throw new Error('messages array is required and cannot be empty');\n    }\n\n    return this.request('/api/conversations', {\n      externalUserId: options.userId,\n      conversationId: options.conversationId,\n      conversationName: options.conversationName,\n      messages: options.messages\n    });\n  }\n\n  /**\n   * Batch track multiple events\n   */\n  async trackBatch(events: Array<{\n    userId: string;\n    event: string;\n    properties?: Record<string, any>;\n  }>) {\n    if (!events || events.length === 0) {\n      throw new Error('events array is required and cannot be empty');\n    }\n\n    const promises = events.map(e => this.track(e.userId, e.event, e.properties));\n    return Promise.all(promises);\n  }\n\n  private async request(endpoint: string, data: any, additionalHeaders?: Record<string, string>) {\n    const url = `${this.baseUrl}${endpoint}`;\n    \n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n    if (this.debug) {\n      console.log(`[Userplex] POST ${url}`, JSON.stringify(data, null, 2));\n    }\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'Authorization': `Bearer ${this.apiKey}`,\n          ...additionalHeaders\n        },\n        body: JSON.stringify(data),\n        signal: controller.signal\n      });\n\n      clearTimeout(timeoutId);\n\n      const responseData = await response.json() as any;\n\n      if (this.debug) {\n        console.log(`[Userplex] Response:`, JSON.stringify(responseData, null, 2));\n      }\n\n      if (!response.ok) {\n        throw new UserplexError(\n          responseData.error || `Request failed with status ${response.status}`,\n          response.status,\n          responseData\n        );\n      }\n\n      return responseData;\n    } catch (error: any) {\n      clearTimeout(timeoutId);\n\n      if (error.name === 'AbortError') {\n        throw new UserplexError('Request timeout', 408);\n      }\n\n      if (error instanceof UserplexError) {\n        throw error;\n      }\n\n      throw new UserplexError(\n        error.message || 'An unexpected error occurred',\n        undefined,\n        error\n      );\n    }\n  }\n}\n\nexport default Userplex;\n\n// For environments that need it separate\nexport { Userplex };\n"]}

package/dist/index.mjs

@@ -0,0 +1,126 @@
+// index.ts
+var UserplexError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "UserplexError";
+  }
+};
+var Userplex = class {
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error("Userplex: API key is required");
+    }
+    if (!apiKey.startsWith("upx_")) {
+      throw new Error('Userplex: API key must start with "upx_"');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || "http://localhost:3000").replace(/\/$/, "");
+    this.timeout = options.timeout || 1e4;
+    this.debug = options.debug || false;
+  }
+  /**
+   * Track an event
+   */
+  async track(userId, event, properties) {
+    if (!userId || !event) {
+      throw new Error("userId and event are required");
+    }
+    return this.request("/api/events", {
+      userId,
+      event,
+      properties: properties || {}
+    });
+  }
+  /**
+   * Identify a user
+   */
+  async identify(externalId, properties) {
+    if (!externalId) {
+      throw new Error("externalId is required");
+    }
+    return this.request("/api/identify", {
+      externalId,
+      ...properties
+    }, {
+      "x-api-key": this.apiKey
+      // identify endpoint uses this header too
+    });
+  }
+  /**
+   * Log a conversation
+   */
+  async logConversation(options) {
+    if (!options.messages || options.messages.length === 0) {
+      throw new Error("messages array is required and cannot be empty");
+    }
+    return this.request("/api/conversations", {
+      externalUserId: options.userId,
+      conversationId: options.conversationId,
+      conversationName: options.conversationName,
+      messages: options.messages
+    });
+  }
+  /**
+   * Batch track multiple events
+   */
+  async trackBatch(events) {
+    if (!events || events.length === 0) {
+      throw new Error("events array is required and cannot be empty");
+    }
+    const promises = events.map((e) => this.track(e.userId, e.event, e.properties));
+    return Promise.all(promises);
+  }
+  async request(endpoint, data, additionalHeaders) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    if (this.debug) {
+      console.log(`[Userplex] POST ${url}`, JSON.stringify(data, null, 2));
+    }
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`,
+          ...additionalHeaders
+        },
+        body: JSON.stringify(data),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const responseData = await response.json();
+      if (this.debug) {
+        console.log(`[Userplex] Response:`, JSON.stringify(responseData, null, 2));
+      }
+      if (!response.ok) {
+        throw new UserplexError(
+          responseData.error || `Request failed with status ${response.status}`,
+          response.status,
+          responseData
+        );
+      }
+      return responseData;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new UserplexError("Request timeout", 408);
+      }
+      if (error instanceof UserplexError) {
+        throw error;
+      }
+      throw new UserplexError(
+        error.message || "An unexpected error occurred",
+        void 0,
+        error
+      );
+    }
+  }
+};
+var index_default = Userplex;
+
+export { Userplex, UserplexError, index_default as default };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Userplex - Simple Analytics SDK\n * \n * Just install and use. No complex setup required.\n * \n * @example\n * ```ts\n * import Userplex from 'userplex';\n * \n * const userplex = new Userplex('upx_your_api_key');\n * \n * // Track events\n * await userplex.track('user123', 'button_clicked', { button: 'signup' });\n * \n * // Identify users\n * await userplex.identify('user123', { email: 'user@example.com' });\n * \n * // Log conversations\n * await userplex.logConversation({\n *   messages: [\n *     { role: 'user', content: 'Hello' },\n *     { role: 'assistant', content: 'Hi there!' }\n *   ]\n * });\n * ```\n */\n\nexport interface ConversationMessage {\n  role: 'user' | 'assistant' | 'system';\n  content: string;\n}\n\nexport interface UserplexOptions {\n  /** Your Userplex instance URL (default: http://localhost:3000) */\n  baseUrl?: string;\n  /** Request timeout in ms (default: 10000) */\n  timeout?: number;\n  /** Enable debug logging (default: false) */\n  debug?: boolean;\n}\n\nexport class UserplexError extends Error {\n  constructor(\n    message: string,\n    public statusCode?: number,\n    public response?: any\n  ) {\n    super(message);\n    this.name = 'UserplexError';\n  }\n}\n\nclass Userplex {\n  private apiKey: string;\n  private baseUrl: string;\n  private timeout: number;\n  private debug: boolean;\n\n  constructor(apiKey: string, options: UserplexOptions = {}) {\n    if (!apiKey) {\n      throw new Error('Userplex: API key is required');\n    }\n    if (!apiKey.startsWith('upx_')) {\n      throw new Error('Userplex: API key must start with \"upx_\"');\n    }\n\n    this.apiKey = apiKey;\n    this.baseUrl = (options.baseUrl || 'http://localhost:3000').replace(/\\/$/, '');\n    this.timeout = options.timeout || 10000;\n    this.debug = options.debug || false;\n  }\n\n  /**\n   * Track an event\n   */\n  async track(userId: string, event: string, properties?: Record<string, any>) {\n    if (!userId || !event) {\n      throw new Error('userId and event are required');\n    }\n\n    return this.request('/api/events', {\n      userId,\n      event,\n      properties: properties || {}\n    });\n  }\n\n  /**\n   * Identify a user\n   */\n  async identify(externalId: string, properties?: Record<string, any>) {\n    if (!externalId) {\n      throw new Error('externalId is required');\n    }\n\n    return this.request('/api/identify', {\n      externalId,\n      ...properties\n    }, {\n      'x-api-key': this.apiKey // identify endpoint uses this header too\n    });\n  }\n\n  /**\n   * Log a conversation\n   */\n  async logConversation(options: {\n    messages: ConversationMessage[];\n    userId?: string;\n    conversationId?: string;\n    conversationName?: string;\n  }) {\n    if (!options.messages || options.messages.length === 0) {\n      throw new Error('messages array is required and cannot be empty');\n    }\n\n    return this.request('/api/conversations', {\n      externalUserId: options.userId,\n      conversationId: options.conversationId,\n      conversationName: options.conversationName,\n      messages: options.messages\n    });\n  }\n\n  /**\n   * Batch track multiple events\n   */\n  async trackBatch(events: Array<{\n    userId: string;\n    event: string;\n    properties?: Record<string, any>;\n  }>) {\n    if (!events || events.length === 0) {\n      throw new Error('events array is required and cannot be empty');\n    }\n\n    const promises = events.map(e => this.track(e.userId, e.event, e.properties));\n    return Promise.all(promises);\n  }\n\n  private async request(endpoint: string, data: any, additionalHeaders?: Record<string, string>) {\n    const url = `${this.baseUrl}${endpoint}`;\n    \n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n    if (this.debug) {\n      console.log(`[Userplex] POST ${url}`, JSON.stringify(data, null, 2));\n    }\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'Authorization': `Bearer ${this.apiKey}`,\n          ...additionalHeaders\n        },\n        body: JSON.stringify(data),\n        signal: controller.signal\n      });\n\n      clearTimeout(timeoutId);\n\n      const responseData = await response.json() as any;\n\n      if (this.debug) {\n        console.log(`[Userplex] Response:`, JSON.stringify(responseData, null, 2));\n      }\n\n      if (!response.ok) {\n        throw new UserplexError(\n          responseData.error || `Request failed with status ${response.status}`,\n          response.status,\n          responseData\n        );\n      }\n\n      return responseData;\n    } catch (error: any) {\n      clearTimeout(timeoutId);\n\n      if (error.name === 'AbortError') {\n        throw new UserplexError('Request timeout', 408);\n      }\n\n      if (error instanceof UserplexError) {\n        throw error;\n      }\n\n      throw new UserplexError(\n        error.message || 'An unexpected error occurred',\n        undefined,\n        error\n      );\n    }\n  }\n}\n\nexport default Userplex;\n\n// For environments that need it separate\nexport { Userplex };\n"]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "userplex",
+  "version": "1.0.0",
+  "description": "Simple analytics SDK for Userplex - Track events, identify users, and log conversations",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "events",
+    "userplex",
+    "observability",
+    "llm",
+    "simple"
+  ],
+  "author": "Userplex",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}