npm package: @meilynx/sdk
Description: Meilynx SDK for AI FinOps telemetry and outcomes ingestion.
Author: Meilynx
Latest version: 0.1.0

# Meilynx JS SDK

[![CI](https://github.com/meilynx/meilynx-js/actions/workflows/ci.yml/badge.svg)](https://github.com/meilynx/meilynx-js/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@meilynx/sdk)](https://www.npmjs.com/package/@meilynx/sdk)
[![License](https://img.shields.io/npm/l/@meilynx/sdk)](LICENSE)

[Meilynx](https://meilynx.com) is an AI governance and FinOps platform that gives enterprises visibility and control
over LLM usage — from cost and compliance to business outcomes. This SDK lets you send structured telemetry and
outcome events from your Node.js applications.

## Install

```bash
npm install @meilynx/sdk
# or
yarn add @meilynx/sdk
# or
pnpm add @meilynx/sdk
```

## Quickstart

### Option 1: Auto-instrumentation (recommended)

Add two lines at startup — existing OpenAI and Anthropic calls are tracked automatically:

```ts
import { MeilynxClient, instrument } from "@meilynx/sdk";

const mx = new MeilynxClient({
  apiKey: process.env.MX_API_KEY,  // baseUrl defaults to https://api.meilynx.com
});

instrument({ client: mx }); // covers OpenAI and Anthropic automatically

// use your AI clients as normal — calls are tracked
import OpenAI from "openai";
const openai = new OpenAI();
await openai.chat.completions.create({ model: "gpt-4o", messages: [...] });

await mx.shutdown();
```

### Option 2: Explicit tracking

Full control over what you send:

```ts
import { MeilynxClient } from "@meilynx/sdk";

const mx = new MeilynxClient({
  apiKey: process.env.MX_API_KEY,  // baseUrl defaults to https://api.meilynx.com
});

mx.track({
  eventType: "llm.response",
  correlationId: "run-123",
  customerId: "cust-acme",
  featureKey: "ask_docs",
  model: "gpt-4o",
  provider: "openai",
  promptTokens: 1200,
  completionTokens: 220,
});

await mx.flush();
```

> **Which to choose?** Use auto-instrumentation (Option 1) for most cases — it automatically captures model,
> latency, and agentic context with zero manual work. Use explicit tracking (Option 2) when you need custom
> event types, non-LLM operations, or providers without built-in integration.

## Configuration

### Environment variables (convention)

The SDK does not read environment variables directly. These are recommended names
for your app configuration:

- `MX_BASE_URL` (optional) — Meilynx API URL
- `MX_API_KEY` — Project-scoped API key (`mx_live_...`)

### Constructor options

| Option | Type | Default | Notes |
| --- | --- | --- | --- |
| `apiKey` | string | — | Required. API key (`mx_live_...`) for `/v1/ingest/*`. |
| `baseUrl` | string | `"https://api.meilynx.com"` | Base URL for the Meilynx API. |
| `sourceSystem` | string | optional | Defaults to `sdk`. |
| `flushAt` | number | optional | Batch size before flush (default 25). |
| `flushIntervalMs` | number | optional | Auto flush interval (default 5000). |
| `maxRetries` | number | optional | Retry attempts on 429/5xx (default 3). |
| `retryDelayMs` | number | optional | Base delay for backoff (default 250). |
| `disableValidation` | boolean | optional | Disable schema validation. |

## Usage patterns

### Event + trace basics

Use `correlationId`, `requestId`, or `sessionId` to connect telemetry and outcomes.

```ts
client.track({
  eventType: "rag.search.completed",
  correlationId: "run-456",
  sessionId: "sess-abc",
  attributes: { latencyMs: 420 }
});
```

### Batching and flushing

The SDK buffers events and flushes automatically. Use `flush()` for deterministic delivery (e.g., request end) and
`shutdown()` to drain queues before process exit.

### Error handling and retries

- Retries occur for HTTP 429 and 5xx responses with exponential backoff.
- 401/403 errors throw immediately with an auth hint.

## Example script

```bash
npm run build
MX_BASE_URL=http://localhost:5000 MX_API_KEY=mx_live_... node examples/send-telemetry.mjs
```

## Compatibility

- **Node.js 18+** (recommended)
- Works in serverless runtimes that support `node:crypto` and `fetch`.
- **Not intended for browsers**. API keys must stay server-side.

## Security and data handling

- Avoid sending sensitive PII unless required for analytics.
- Prefer hashed or pseudonymous IDs (e.g., `customerId`, `endUserId`).
- Redact secrets from `attributes` before sending.

## Docs

- Documentation: [docs.meilynx.com](https://docs.meilynx.com)
- Python SDK: [github.com/meilynx/meilynx-python](https://github.com/meilynx/meilynx-python)
- .NET SDK: [github.com/meilynx/meilynx-dotnet](https://github.com/meilynx/meilynx-dotnet)

## Roadmap

- OpenTelemetry bridge for trace export
- Edge runtime optimizations
- Built-in redaction helpers

## License

MIT