userplex 0.1.0 → 1.0.1

package/README.md

@@ -1,369 +1,324 @@
-# Userplex TypeScript API Library
+# Userplex
 
-[![NPM version](<https://img.shields.io/npm/v/userplex.svg?label=npm%20(stable)>)](https://npmjs.org/package/userplex) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/userplex)
-
-This library provides convenient access to the Userplex REST API from server-side TypeScript or JavaScript.
-
-The full API of this library can be found in [api.md](api.md).
-
-It is generated with [Stainless](https://www.stainless.com/).
+Dead simple analytics SDK. No complex setup. Just track.
 
 ## Installation
 
-```sh
+```bash
 npm install userplex
 ```
 
 ## Usage
 
-The full API of this library can be found in [api.md](api.md).
-
-<!-- prettier-ignore -->
-```js
+```javascript
 import Userplex from 'userplex';
 
-const client = new Userplex({
-  apiKey: process.env['USERPLEX_API_KEY'], // This is the default and can be omitted
-});
+// Initialize with your API key (connects to userplex.vercel.app by default)
+const userplex = new Userplex('upx_your_api_key_here');
 
-const response = await client.users.identify({
-  email: 'REPLACE_ME',
-  name: 'REPLACE_ME',
-  userId: 'REPLACE_ME',
+// Or use your own Userplex instance
+const customUserplex = new Userplex('upx_your_api_key_here', {
+  baseUrl: 'https://your-userplex-instance.com'
 });
 
-console.log(response.success);
-```
-
-### Request & Response types
-
-This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
-
-<!-- prettier-ignore -->
-```ts
-import Userplex from 'userplex';
-
-const client = new Userplex({
-  apiKey: process.env['USERPLEX_API_KEY'], // This is the default and can be omitted
+// Track events
+await userplex.track('user123', 'button_clicked', {
+  button: 'signup',
+  page: '/pricing'
 });
 
-const params: Userplex.UserIdentifyParams = { email: 'REPLACE_ME', name: 'REPLACE_ME', userId: 'REPLACE_ME' };
-const response: Userplex.UserIdentifyResponse = await client.users.identify(params);
-```
+// Identify users
+await userplex.identify('user123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'premium'
+});
 
-Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
-
-## Handling errors
-
-When the library is unable to connect to the API,
-or if the API returns a non-success status code (i.e., 4xx or 5xx response),
-a subclass of `APIError` will be thrown:
-
-<!-- prettier-ignore -->
-```ts
-const response = await client.users
-  .identify({ email: 'REPLACE_ME', name: 'REPLACE_ME', userId: 'REPLACE_ME' })
-  .catch(async (err) => {
-    if (err instanceof Userplex.APIError) {
-      console.log(err.status); // 400
-      console.log(err.name); // BadRequestError
-      console.log(err.headers); // {server: 'nginx', ...}
-    } else {
-      throw err;
-    }
-  });
+// 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.' }
+  ]
+});
 ```
 
-Error codes are as follows:
+That's it. No route setup. No configuration files. Just analytics.
 
-| Status Code | Error Type                 |
-| ----------- | -------------------------- |
-| 400         | `BadRequestError`          |
-| 401         | `AuthenticationError`      |
-| 403         | `PermissionDeniedError`    |
-| 404         | `NotFoundError`            |
-| 422         | `UnprocessableEntityError` |
-| 429         | `RateLimitError`           |
-| >=500       | `InternalServerError`      |
-| N/A         | `APIConnectionError`       |
+## API
 
-### Retries
+### `new Userplex(apiKey, options?)`
 
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
-429 Rate Limit, and >=500 Internal errors will all be retried by default.
+Create a new Userplex instance.
 
-You can use the `maxRetries` option to configure or disable this:
-
-<!-- prettier-ignore -->
-```js
-// Configure the default for all requests:
-const client = new Userplex({
-  maxRetries: 0, // default is 2
-});
+- `apiKey` - Your Userplex API key (required)
+- `options` - Optional configuration
+  - `baseUrl` - Your Userplex server URL (default: `https://userplex.vercel.app`)
+  - `timeout` - Request timeout in ms (default: `10000`)
+  - `debug` - Enable debug logging (default: `false`)
 
-// Or, configure per-request:
-await client.users.identify({ email: 'REPLACE_ME', name: 'REPLACE_ME', userId: 'REPLACE_ME' }, {
-  maxRetries: 5,
+```javascript
+const userplex = new Userplex('upx_key', {
+  baseUrl: 'https://analytics.myapp.com',
+  timeout: 30000,
+  debug: true
 });
 ```
 
-### Timeouts
+### `track(userId, event, properties?)`
 
-Requests time out after 1 minute by default. You can configure this with a `timeout` option:
+Track an event.
 
-<!-- prettier-ignore -->
-```ts
-// Configure the default for all requests:
-const client = new Userplex({
-  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
-});
-
-// Override per-request:
-await client.users.identify({ email: 'REPLACE_ME', name: 'REPLACE_ME', userId: 'REPLACE_ME' }, {
-  timeout: 5 * 1000,
+```javascript
+await userplex.track('user123', 'purchase_completed', {
+  amount: 99.99,
+  currency: 'USD',
+  items: ['product1', 'product2']
 });
 ```
 
-On timeout, an `APIConnectionTimeoutError` is thrown.
-
-Note that requests which time out will be [retried twice by default](#retries).
-
-## Advanced Usage
-
-### Accessing raw Response data (e.g., headers)
-
-The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
-This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
-
-You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
-Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
-
-<!-- prettier-ignore -->
-```ts
-const client = new Userplex();
+### `identify(userId, properties?)`
 
-const response = await client.users
-  .identify({ email: 'REPLACE_ME', name: 'REPLACE_ME', userId: 'REPLACE_ME' })
-  .asResponse();
-console.log(response.headers.get('X-My-Header'));
-console.log(response.statusText); // access the underlying Response object
+Identify a user and set their properties.
 
-const { data: response, response: raw } = await client.users
-  .identify({ email: 'REPLACE_ME', name: 'REPLACE_ME', userId: 'REPLACE_ME' })
-  .withResponse();
-console.log(raw.headers.get('X-My-Header'));
-console.log(response.success);
+```javascript
+await userplex.identify('user123', {
+  email: 'john@example.com',
+  company: 'Acme Corp',
+  role: 'admin',
+  plan: 'enterprise'
+});
 ```
 
-### Logging
-
-> [!IMPORTANT]
-> All log messages are intended for debugging only. The format and content of log messages
-> may change between releases.
-
-#### Log levels
-
-The log level can be configured in two ways:
+### `logConversation(options)`
 
-1. Via the `USERPLEX_LOG` environment variable
-2. Using the `logLevel` client option (overrides the environment variable if set)
+Log an LLM conversation for observability.
 
-```ts
-import Userplex from 'userplex';
-
-const client = new Userplex({
-  logLevel: 'debug', // Show all log messages
+```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?' }
+  ]
 });
 ```
 
-Available log levels, from most to least verbose:
+### `trackBatch(events)`
 
-- `'debug'` - Show debug messages, info, warnings, and errors
-- `'info'` - Show info messages, warnings, and errors
-- `'warn'` - Show warnings and errors (default)
-- `'error'` - Show only errors
-- `'off'` - Disable all logging
+Track multiple events at once.
 
-At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
-Some authentication-related headers are redacted, but sensitive data in request and response bodies
-may still be visible.
+```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' } }
+]);
+```
 
-#### Custom logger
+## Using in Different Environments
 
-By default, this library logs to `globalThis.console`. You can also provide a custom logger.
-Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+### Node.js / Server-side
 
-When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
-below the configured level will not be sent to your logger.
+Use it directly with your API key:
 
-```ts
+```javascript
+// server.js
 import Userplex from 'userplex';
-import pino from 'pino';
 
-const logger = pino();
+const userplex = new Userplex(process.env.USERPLEX_API_KEY);
 
-const client = new Userplex({
-  logger: logger.child({ name: 'Userplex' }),
-  logLevel: 'debug', // Send all messages to pino, allowing it to filter
+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 });
 });
 ```
 
-### Making custom/undocumented requests
+### Next.js API Routes
 
-This library is typed for convenient access to the documented API. If you need to access undocumented
-endpoints, params, or response properties, the library can still be used.
-
-#### Undocumented endpoints
-
-To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
-Options on the client, such as retries, will be respected when making these requests.
-
-```ts
-await client.post('/some/path', {
-  body: { some_prop: 'foo' },
-  query: { some_query_arg: 'bar' },
-});
-```
-
-#### Undocumented request params
+```javascript
+// app/api/checkout/route.js
+import Userplex from 'userplex';
 
-To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
-parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
-send will be sent as-is.
+const userplex = new Userplex(process.env.USERPLEX_API_KEY);
 
-```ts
-client.users.identify({
-  // ...
-  // @ts-expect-error baz is not yet public
-  baz: 'undocumented option',
-});
+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 });
+}
 ```
 
-For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
-extra param in the body.
+### Client-side (Browser)
 
-If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
-options.
+⚠️ **Never put your API key in client-side code!** 
 
-#### Undocumented response properties
+For client-side tracking, you have two options:
 
-To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
-the response object, or cast the response object to the requisite type. Like the request params, we do not
-validate or strip extra properties from the response from the API.
+#### Option 1: Create a simple API endpoint
 
-### Customizing the fetch client
+```javascript
+// app/api/track/route.js (Next.js example)
+import Userplex from 'userplex';
 
-By default, this library expects a global `fetch` function is defined.
+const userplex = new Userplex(process.env.USERPLEX_API_KEY);
 
-If you want to use a different `fetch` function, you can either polyfill the global:
+export async function POST(request) {
+  const { userId, event, properties } = await request.json();
+  await userplex.track(userId, event, properties);
+  return Response.json({ success: true });
+}
+```
 
-```ts
-import fetch from 'my-fetch';
+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
+    })
+  });
+}
 
-globalThis.fetch = fetch;
+// Use it
+trackEvent('button_clicked', { button: 'signup' });
 ```
 
-Or pass it to the client:
+#### Option 2: Use environment-specific initialization
 
-```ts
+```javascript
+// lib/analytics.js
 import Userplex from 'userplex';
-import fetch from 'my-fetch';
 
-const client = new Userplex({ fetch });
+// 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;
 ```
 
-### Fetch options
-
-If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
-
-```ts
-import Userplex from 'userplex';
-
-const client = new Userplex({
-  fetchOptions: {
-    // `RequestInit` options
-  },
-});
+## 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);
+  }
+}
 ```
 
-#### Configuring proxies
+## TypeScript
 
-To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
-options to requests:
+Full TypeScript support included:
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
+```typescript
+import Userplex, { ConversationMessage, UserplexError } from 'userplex';
 
-```ts
-import Userplex from 'userplex';
-import * as undici from 'undici';
+const userplex = new Userplex('upx_key');
 
-const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
-const client = new Userplex({
-  fetchOptions: {
-    dispatcher: proxyAgent,
-  },
-});
+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
+  }
+}
 ```
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
+## Examples
 
-```ts
-import Userplex from 'userplex';
+### E-commerce Tracking
 
-const client = new Userplex({
-  fetchOptions: {
-    proxy: 'http://localhost:8888',
-  },
-});
+```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 });
 ```
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+### SaaS Application
 
-```ts
-import Userplex from 'npm:userplex';
+```javascript
+// Track feature usage
+await userplex.track(userId, 'feature_used', {
+  feature: 'csv_export',
+  recordCount: 1000
+});
 
-const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
-const client = new Userplex({
-  fetchOptions: {
-    client: httpClient,
-  },
+// Track subscription changes
+await userplex.identify(userId, {
+  plan: 'enterprise',
+  mrr: 499
 });
 ```
 
-## Frequently Asked Questions
-
-## Semantic versioning
+### AI Application
 
-This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
+```javascript
+// Log every conversation for debugging and analytics
+const messages = [];
 
-1. Changes that only affect static types, without breaking runtime behavior.
-2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
-3. Changes that we do not expect to impact the vast majority of users in practice.
+// User asks a question
+messages.push({ role: 'user', content: userInput });
 
-We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
+// Get AI response
+const response = await callOpenAI(messages);
+messages.push({ role: 'assistant', content: response });
 
-We are keen for your feedback; please open an [issue](https://www.github.com/dqnamo/userplex-typescript/issues) with questions, bugs, or suggestions.
-
-## Requirements
-
-TypeScript >= 4.9 is supported.
-
-The following runtimes are supported:
-
-- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
-- Deno v1.28.0 or higher.
-- Bun 1.0 or later.
-- Cloudflare Workers.
-- Vercel Edge Runtime.
-- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
-- Nitro v2.6 or greater.
-
-Note that React Native is not supported at this time.
-
-If you are interested in other runtime environments, please open or upvote an issue on GitHub.
+// Log to Userplex
+await userplex.logConversation({
+  userId: currentUser.id,
+  conversationName: 'Chat Session',
+  messages
+});
+```
 
-## Contributing
+## License
 
-See [the contributing documentation](./CONTRIBUTING.md).
+MIT