@analytix402/sdk 0.1.1 → 0.1.3

package/README.md

@@ -106,6 +106,52 @@ These paths are excluded from tracking by default:
 
 `/health`, `/healthz`, `/ready`, `/readyz`, `/live`, `/livez`, `/metrics`, `/favicon.ico`, `/.well-known`
 
+## Agent Tracking
+
+Track AI agent health, tasks, and LLM usage:
+
+```typescript
+import { createAnalytix402Client } from '@analytix402/sdk';
+
+const client = createAnalytix402Client({
+  apiKey: 'ax_live_xxxxx',
+  agentId: 'my-trading-agent',
+  agentName: 'Trading Bot',
+});
+
+// Send heartbeats to show agent is alive
+setInterval(() => {
+  client.heartbeat('healthy', { uptime: process.uptime() });
+}, 30000);
+
+// Track tasks with automatic duration measurement
+const task = client.startTask('rebalance-portfolio-42');
+try {
+  await doRebalance();
+  task.end(true, { positions: 12 });
+} catch (err) {
+  task.end(false, { error: err.message });
+}
+
+// Track LLM token usage
+client.trackLLM({
+  model: 'claude-sonnet-4-5-20250929',
+  provider: 'anthropic',
+  inputTokens: 1500,
+  outputTokens: 300,
+  costUsd: 0.012,
+  durationMs: 820,
+  taskId: 'rebalance-portfolio-42',
+});
+
+// Report task outcomes directly
+client.reportOutcome('task-123', true, {
+  durationMs: 2400,
+  cost: 0.05,
+  metadata: { pnl: 12.50 },
+});
+```
+
 ## Manual Tracking
 
 For non-Express frameworks or custom tracking:
@@ -140,6 +186,29 @@ await client.flush();
 await client.shutdown();
 ```
 
+## Proxy URL Integration
+
+Instead of the SDK middleware, you can route API calls through Analytix402's proxy:
+
+```
+https://analytix402.com/api/p/{your-api-slug}/your/endpoint
+```
+
+Pass your spend key as a header:
+
+```typescript
+const response = await fetch(
+  'https://analytix402.com/api/p/weather-api/forecast?city=NYC',
+  {
+    headers: {
+      'X-Spend-Key': 'sk_live_your_spend_key',
+    },
+  }
+);
+```
+
+The proxy handles payment, analytics tracking, and circuit breaker enforcement automatically.
+
 ## Performance
 
 - **< 50ms overhead** per request

package/dist/chunk-GV5RDHUW.mjs

@@ -0,0 +1,259 @@
+// src/client.ts
+var SDK_NAME = "@analytix402/sdk";
+var SDK_VERSION = "0.1.1";
+var DEFAULT_CONFIG = {
+  baseUrl: "https://analytix402.com",
+  debug: false,
+  batchSize: 100,
+  flushInterval: 5e3,
+  maxRetries: 3,
+  maxQueueSize: 1e3,
+  timeout: 1e4,
+  excludePaths: ["/health", "/healthz", "/ready", "/metrics", "/favicon.ico"],
+  autoConnect: false,
+  heartbeatIntervalMs: 0
+};
+function createClient(config) {
+  if (!config.apiKey) {
+    throw new Error("Analytix402: apiKey is required");
+  }
+  if (!config.apiKey.startsWith("ax_live_") && !config.apiKey.startsWith("ax_test_")) {
+    console.warn("Analytix402: API key should start with ax_live_ or ax_test_");
+  }
+  const cfg = {
+    ...DEFAULT_CONFIG,
+    ...config
+  };
+  const agentId = cfg.agentId;
+  const queue = [];
+  let flushTimer = null;
+  let heartbeatTimer = null;
+  let isFlushing = false;
+  let isShutdown = false;
+  const log = (...args) => {
+    if (cfg.debug) {
+      console.log("[Analytix402]", ...args);
+    }
+  };
+  const warn = (...args) => {
+    console.warn("[Analytix402]", ...args);
+  };
+  function enqueue(event) {
+    if (isShutdown) {
+      warn("Client is shutdown, event dropped");
+      return;
+    }
+    if (queue.length >= cfg.maxQueueSize) {
+      warn(`Queue full (${cfg.maxQueueSize}), dropping oldest event`);
+      queue.shift();
+    }
+    queue.push({
+      event,
+      attempts: 0,
+      addedAt: Date.now()
+    });
+    log(`Event queued (${queue.length} in queue)`);
+    if (queue.length >= cfg.batchSize) {
+      log("Batch size reached, flushing");
+      flush();
+    } else if (!flushTimer) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush();
+      }, cfg.flushInterval);
+    }
+  }
+  function track(event) {
+    if (agentId && !event.agentId) {
+      event.agentId = agentId;
+    }
+    enqueue(event);
+  }
+  function heartbeat(status = "healthy", metadata) {
+    if (!agentId) {
+      warn("heartbeat() requires agentId in config");
+      return;
+    }
+    const event = {
+      type: "heartbeat",
+      agentId,
+      status,
+      metadata,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    enqueue(event);
+  }
+  function reportOutcome(taskId, success, options) {
+    const event = {
+      type: "task_outcome",
+      agentId,
+      taskId,
+      success,
+      durationMs: options?.durationMs,
+      cost: options?.cost,
+      metadata: options?.metadata,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    enqueue(event);
+  }
+  function startTask(taskId) {
+    const id = taskId || `task_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    const startTime = Date.now();
+    return {
+      taskId: id,
+      end(success, metadata) {
+        const durationMs = Date.now() - startTime;
+        reportOutcome(id, success, { durationMs, metadata });
+      }
+    };
+  }
+  function trackLLM(usage) {
+    const event = {
+      type: "llm_usage",
+      agentId,
+      taskId: usage.taskId,
+      model: usage.model,
+      provider: usage.provider,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      totalTokens: usage.inputTokens + usage.outputTokens,
+      costUsd: usage.costUsd,
+      durationMs: usage.durationMs,
+      metadata: usage.metadata,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    enqueue(event);
+  }
+  async function sendBatch(events) {
+    if (events.length === 0) return true;
+    const payload = {
+      events,
+      sdk: {
+        name: SDK_NAME,
+        version: SDK_VERSION
+      },
+      sentAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), cfg.timeout);
+      const response = await fetch(`${cfg.baseUrl}/api/ingest/batch`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": cfg.apiKey,
+          "User-Agent": `${SDK_NAME}/${SDK_VERSION}`
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const text = await response.text().catch(() => "Unknown error");
+        throw new Error(`HTTP ${response.status}: ${text}`);
+      }
+      log(`Sent ${events.length} events successfully`);
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        warn("Request timed out");
+      } else {
+        warn("Failed to send events:", error);
+      }
+      return false;
+    }
+  }
+  async function flush() {
+    if (isFlushing || queue.length === 0) {
+      return;
+    }
+    isFlushing = true;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    const batch = queue.splice(0, cfg.batchSize);
+    const events = batch.map((q) => q.event);
+    log(`Flushing ${events.length} events`);
+    const success = await sendBatch(events);
+    if (!success) {
+      const retriable = batch.filter((q) => q.attempts < cfg.maxRetries);
+      if (retriable.length > 0) {
+        log(`Re-queuing ${retriable.length} events for retry`);
+        for (const item of retriable.reverse()) {
+          item.attempts++;
+          queue.unshift(item);
+        }
+        const backoff = Math.min(1e3 * Math.pow(2, retriable[0].attempts), 3e4);
+        log(`Retry scheduled in ${backoff}ms`);
+        flushTimer = setTimeout(() => {
+          flushTimer = null;
+          flush();
+        }, backoff);
+      } else {
+        warn(`Dropped ${batch.length} events after ${cfg.maxRetries} retries`);
+      }
+    }
+    isFlushing = false;
+    if (queue.length > 0 && !flushTimer) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush();
+      }, cfg.flushInterval);
+    }
+  }
+  async function shutdown() {
+    log("Shutting down...");
+    isShutdown = true;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (queue.length > 0) {
+      log(`Flushing ${queue.length} remaining events`);
+      isFlushing = false;
+      await flush();
+    }
+    log("Shutdown complete");
+  }
+  if (typeof process !== "undefined") {
+    const handleExit = () => {
+      shutdown().catch(console.error);
+    };
+    process.on("beforeExit", handleExit);
+    process.on("SIGINT", handleExit);
+    process.on("SIGTERM", handleExit);
+  }
+  if (cfg.autoConnect && agentId) {
+    log("Auto-connect enabled, sending registration heartbeat");
+    heartbeat("healthy", { event: "sdk_connected" });
+  }
+  if (cfg.heartbeatIntervalMs && cfg.heartbeatIntervalMs > 0 && agentId) {
+    log(`Starting periodic heartbeat every ${cfg.heartbeatIntervalMs}ms`);
+    heartbeatTimer = setInterval(() => {
+      if (!isShutdown) {
+        heartbeat("healthy", { event: "periodic" });
+      }
+    }, cfg.heartbeatIntervalMs);
+    if (heartbeatTimer && typeof heartbeatTimer === "object" && "unref" in heartbeatTimer) {
+      heartbeatTimer.unref();
+    }
+  }
+  return {
+    track,
+    flush,
+    shutdown,
+    heartbeat,
+    reportOutcome,
+    startTask,
+    trackLLM
+  };
+}
+
+export {
+  createClient
+};

package/dist/chunk-KSO5EEA2.mjs

@@ -0,0 +1,156 @@
+import {
+  createClient
+} from "./chunk-GV5RDHUW.mjs";
+
+// src/wrappers/fetch.ts
+var X402_HEADERS = {
+  PAYMENT: "x-payment",
+  PAYMENT_RESPONSE: "x-payment-response",
+  PAYER: "x-payer",
+  AMOUNT: "x-payment-amount",
+  CURRENCY: "x-payment-currency",
+  TX_HASH: "x-payment-tx",
+  FACILITATOR: "x-facilitator"
+};
+function extractPaymentFromResponse(headers) {
+  const txHash = headers.get(X402_HEADERS.TX_HASH) || headers.get(X402_HEADERS.PAYMENT_RESPONSE);
+  const amount = headers.get(X402_HEADERS.AMOUNT);
+  if (!txHash && !amount) return void 0;
+  return {
+    amount: amount || "0",
+    currency: headers.get(X402_HEADERS.CURRENCY) || "USDC",
+    wallet: headers.get(X402_HEADERS.PAYER) || "",
+    status: "success",
+    txHash: txHash || void 0,
+    facilitator: headers.get(X402_HEADERS.FACILITATOR) || void 0
+  };
+}
+function extractPaymentFromRequest(headers) {
+  const paymentProof = headers[X402_HEADERS.PAYMENT] || headers[X402_HEADERS.TX_HASH];
+  if (!paymentProof) return void 0;
+  return {
+    amount: headers[X402_HEADERS.AMOUNT] || "0",
+    currency: headers[X402_HEADERS.CURRENCY] || "USDC",
+    wallet: headers[X402_HEADERS.PAYER] || "",
+    status: "pending",
+    // outbound — not yet confirmed
+    txHash: headers[X402_HEADERS.TX_HASH] || void 0,
+    facilitator: headers[X402_HEADERS.FACILITATOR] || void 0
+  };
+}
+function shouldExclude(url, patterns) {
+  for (const pattern of patterns) {
+    if (pattern.includes("*")) {
+      const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+      if (regex.test(url)) return true;
+    } else if (url.includes(pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+function parseUrl(input) {
+  let urlStr;
+  if (typeof input === "string") {
+    urlStr = input;
+  } else if (input instanceof URL) {
+    urlStr = input.toString();
+  } else if (typeof input === "object" && "url" in input) {
+    urlStr = input.url;
+  } else {
+    urlStr = String(input);
+  }
+  try {
+    const parsed = new URL(urlStr);
+    return { url: urlStr, hostname: parsed.hostname, pathname: parsed.pathname };
+  } catch {
+    return { url: urlStr, hostname: "", pathname: urlStr };
+  }
+}
+function headersToRecord(init) {
+  const raw = init?.headers;
+  if (!raw) return {};
+  const result = {};
+  if (raw instanceof Headers) {
+    raw.forEach((v, k) => {
+      result[k.toLowerCase()] = v;
+    });
+  } else if (Array.isArray(raw)) {
+    for (const [k, v] of raw) {
+      result[k.toLowerCase()] = v;
+    }
+  } else {
+    for (const [k, v] of Object.entries(raw)) {
+      result[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : String(v);
+    }
+  }
+  return result;
+}
+function createAnalytix402Fetch(options) {
+  const client = createClient(options);
+  const onlyPayments = options.onlyPayments ?? false;
+  const excludeUrls = [
+    ...options.excludeUrls || [],
+    // Never track calls back to Analytix402 itself
+    "*analytix402.com*"
+  ];
+  const wrappedFetch = async function analytix402Fetch(input, init) {
+    const { url, pathname } = parseUrl(input);
+    if (shouldExclude(url, excludeUrls)) {
+      return fetch(input, init);
+    }
+    const method = init?.method?.toUpperCase() || "GET";
+    const requestHeaders = headersToRecord(init);
+    const outboundPayment = extractPaymentFromRequest(requestHeaders);
+    const start = Date.now();
+    let response;
+    try {
+      response = await fetch(input, init);
+    } catch (error) {
+      const event2 = {
+        type: "request",
+        method,
+        path: pathname,
+        endpoint: url,
+        statusCode: 0,
+        responseTimeMs: Date.now() - start,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        agentId: options.agentId,
+        payment: outboundPayment,
+        metadata: {
+          error: error instanceof Error ? error.message : String(error)
+        }
+      };
+      client.track(event2);
+      throw error;
+    }
+    const responseTimeMs = Date.now() - start;
+    const responsePayment = extractPaymentFromResponse(response.headers);
+    const is402 = response.status === 402;
+    const hasPayment = !!(outboundPayment || responsePayment);
+    if (onlyPayments && !hasPayment && !is402) {
+      return response;
+    }
+    const payment = responsePayment || outboundPayment;
+    const event = {
+      type: "request",
+      method,
+      path: pathname,
+      endpoint: url,
+      statusCode: response.status,
+      responseTimeMs,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      agentId: options.agentId,
+      payment: payment || void 0,
+      metadata: is402 ? { paymentRequired: true } : void 0
+    };
+    client.track(event);
+    return response;
+  };
+  wrappedFetch.client = client;
+  return wrappedFetch;
+}
+
+export {
+  createAnalytix402Fetch
+};

package/dist/chunk-MIPQLCB6.mjs

@@ -0,0 +1,85 @@
+import {
+  createClient
+} from "./chunk-GV5RDHUW.mjs";
+
+// src/wrappers/openai.ts
+var DEFAULT_COSTS = {
+  "gpt-4o": { input: 2.5, output: 10 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+  "o1": { input: 15, output: 60 },
+  "o1-mini": { input: 3, output: 12 },
+  "o3-mini": { input: 1.1, output: 4.4 }
+};
+function estimateCost(model, inputTokens, outputTokens, customCosts) {
+  const costs = customCosts ?? DEFAULT_COSTS;
+  let pricing = costs[model];
+  if (!pricing) {
+    const prefix = Object.keys(costs).find((k) => model.startsWith(k));
+    if (prefix) pricing = costs[prefix];
+  }
+  if (!pricing) return void 0;
+  return inputTokens / 1e6 * pricing.input + outputTokens / 1e6 * pricing.output;
+}
+function withAnalytix(openai, options) {
+  const client = createClient(options);
+  const customCosts = options.costPerMillionTokens;
+  const originalCreate = openai.chat.completions.create.bind(openai.chat.completions);
+  const trackedCreate = async function(body, opts) {
+    const start = Date.now();
+    const model = body.model || "unknown";
+    try {
+      const result = await originalCreate(body, opts);
+      const durationMs = Date.now() - start;
+      const inputTokens = result.usage?.prompt_tokens ?? 0;
+      const outputTokens = result.usage?.completion_tokens ?? 0;
+      const costUsd = estimateCost(model, inputTokens, outputTokens, customCosts);
+      client.trackLLM({
+        model,
+        provider: "openai",
+        inputTokens,
+        outputTokens,
+        costUsd,
+        durationMs,
+        metadata: {
+          completionId: result.id
+        }
+      });
+      return result;
+    } catch (error) {
+      const durationMs = Date.now() - start;
+      client.trackLLM({
+        model,
+        provider: "openai",
+        inputTokens: 0,
+        outputTokens: 0,
+        durationMs,
+        metadata: {
+          error: error instanceof Error ? error.message : String(error)
+        }
+      });
+      throw error;
+    }
+  };
+  const proxiedCompletions = Object.create(openai.chat.completions, {
+    create: { value: trackedCreate, writable: true, configurable: true }
+  });
+  const proxiedChat = Object.create(openai.chat, {
+    completions: { value: proxiedCompletions, writable: true, configurable: true }
+  });
+  const proxied = Object.create(openai, {
+    chat: { value: proxiedChat, writable: true, configurable: true }
+  });
+  proxied.__analytix402 = client;
+  return proxied;
+}
+function getAnalytixClient(openai) {
+  return openai.__analytix402;
+}
+
+export {
+  withAnalytix,
+  getAnalytixClient
+};

package/dist/chunk-PQO3A7RN.mjs

@@ -0,0 +1,82 @@
+import {
+  createClient
+} from "./chunk-GV5RDHUW.mjs";
+
+// src/wrappers/anthropic.ts
+var DEFAULT_COSTS = {
+  "claude-opus-4-6": { input: 15, output: 75 },
+  "claude-sonnet-4-5-20250929": { input: 3, output: 15 },
+  "claude-haiku-4-5-20251001": { input: 0.8, output: 4 },
+  "claude-3-5-sonnet": { input: 3, output: 15 },
+  "claude-3-5-haiku": { input: 0.8, output: 4 },
+  "claude-3-opus": { input: 15, output: 75 },
+  "claude-3-sonnet": { input: 3, output: 15 },
+  "claude-3-haiku": { input: 0.25, output: 1.25 }
+};
+function estimateCost(model, inputTokens, outputTokens, customCosts) {
+  const costs = customCosts ?? DEFAULT_COSTS;
+  let pricing = costs[model];
+  if (!pricing) {
+    const prefix = Object.keys(costs).find((k) => model.startsWith(k));
+    if (prefix) pricing = costs[prefix];
+  }
+  if (!pricing) return void 0;
+  return inputTokens / 1e6 * pricing.input + outputTokens / 1e6 * pricing.output;
+}
+function withAnalytix(anthropic, options) {
+  const client = createClient(options);
+  const customCosts = options.costPerMillionTokens;
+  const originalCreate = anthropic.messages.create.bind(anthropic.messages);
+  const trackedCreate = async function(body, opts) {
+    const start = Date.now();
+    const model = body.model || "unknown";
+    try {
+      const result = await originalCreate(body, opts);
+      const durationMs = Date.now() - start;
+      const inputTokens = result.usage?.input_tokens ?? 0;
+      const outputTokens = result.usage?.output_tokens ?? 0;
+      const costUsd = estimateCost(model, inputTokens, outputTokens, customCosts);
+      client.trackLLM({
+        model,
+        provider: "anthropic",
+        inputTokens,
+        outputTokens,
+        costUsd,
+        durationMs,
+        metadata: {
+          messageId: result.id
+        }
+      });
+      return result;
+    } catch (error) {
+      const durationMs = Date.now() - start;
+      client.trackLLM({
+        model,
+        provider: "anthropic",
+        inputTokens: 0,
+        outputTokens: 0,
+        durationMs,
+        metadata: {
+          error: error instanceof Error ? error.message : String(error)
+        }
+      });
+      throw error;
+    }
+  };
+  const proxiedMessages = Object.create(anthropic.messages, {
+    create: { value: trackedCreate, writable: true, configurable: true }
+  });
+  const proxied = Object.create(anthropic, {
+    messages: { value: proxiedMessages, writable: true, configurable: true }
+  });
+  proxied.__analytix402 = client;
+  return proxied;
+}
+function getAnalytixClient(anthropic) {
+  return anthropic.__analytix402;
+}
+
+export {
+  withAnalytix,
+  getAnalytixClient
+};