@analytix402/sdk 0.1.0 → 0.1.2

package/dist/wrappers/fetch.js

@@ -0,0 +1,434 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/wrappers/fetch.ts
+var fetch_exports = {};
+__export(fetch_exports, {
+  createAnalytix402Fetch: () => createAnalytix402Fetch
+});
+module.exports = __toCommonJS(fetch_exports);
+
+// 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
+  };
+}
+
+// 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;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAnalytix402Fetch
+});

package/dist/wrappers/fetch.mjs

@@ -0,0 +1,7 @@
+import {
+  createAnalytix402Fetch
+} from "../chunk-KSO5EEA2.mjs";
+import "../chunk-GV5RDHUW.mjs";
+export {
+  createAnalytix402Fetch
+};

package/dist/wrappers/openai.d.mts

@@ -0,0 +1,69 @@
+import { A as Analytix402Config, a as Analytix402Client } from '../types-C67qDpYb.mjs';
+
+/**
+ * Analytix402 OpenAI Wrapper
+ *
+ * Auto-instruments OpenAI SDK calls to track LLM usage,
+ * costs, and latency through Analytix402.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from 'openai';
+ * import { withAnalytix } from '@analytix402/sdk/openai';
+ *
+ * const openai = withAnalytix(new OpenAI(), {
+ *   apiKey: 'ax_live_your_key_here',
+ * });
+ *
+ * // All calls are now auto-tracked
+ * const res = await openai.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello' }],
+ * });
+ * ```
+ */
+
+/** Minimal OpenAI SDK shape — avoids hard dependency on the openai package. */
+interface OpenAICompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+}
+interface OpenAICompletion {
+    id?: string;
+    model?: string;
+    usage?: OpenAICompletionUsage;
+    [key: string]: unknown;
+}
+interface OpenAIChatCompletions {
+    create(body: Record<string, unknown>, options?: Record<string, unknown>): Promise<OpenAICompletion>;
+}
+interface OpenAIChat {
+    completions: OpenAIChatCompletions;
+}
+interface OpenAILike {
+    chat: OpenAIChat;
+    [key: string]: unknown;
+}
+interface OpenAIWrapperOptions extends Analytix402Config {
+    /**
+     * Override cost table (USD per 1 million tokens).
+     * Keys are model names; values have `input` and `output` fields.
+     */
+    costPerMillionTokens?: Record<string, {
+        input: number;
+        output: number;
+    }>;
+}
+/**
+ * Wrap an OpenAI SDK instance to auto-track LLM usage via Analytix402.
+ *
+ * Returns a proxied instance — the original is not mutated.
+ */
+declare function withAnalytix<T extends OpenAILike>(openai: T, options: OpenAIWrapperOptions): T;
+/**
+ * Access the Analytix402 client from a wrapped OpenAI instance.
+ */
+declare function getAnalytixClient(openai: OpenAILike): Analytix402Client | undefined;
+
+export { type OpenAIWrapperOptions, getAnalytixClient, withAnalytix };

package/dist/wrappers/openai.d.ts

@@ -0,0 +1,69 @@
+import { A as Analytix402Config, a as Analytix402Client } from '../types-C67qDpYb.js';
+
+/**
+ * Analytix402 OpenAI Wrapper
+ *
+ * Auto-instruments OpenAI SDK calls to track LLM usage,
+ * costs, and latency through Analytix402.
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from 'openai';
+ * import { withAnalytix } from '@analytix402/sdk/openai';
+ *
+ * const openai = withAnalytix(new OpenAI(), {
+ *   apiKey: 'ax_live_your_key_here',
+ * });
+ *
+ * // All calls are now auto-tracked
+ * const res = await openai.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello' }],
+ * });
+ * ```
+ */
+
+/** Minimal OpenAI SDK shape — avoids hard dependency on the openai package. */
+interface OpenAICompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+}
+interface OpenAICompletion {
+    id?: string;
+    model?: string;
+    usage?: OpenAICompletionUsage;
+    [key: string]: unknown;
+}
+interface OpenAIChatCompletions {
+    create(body: Record<string, unknown>, options?: Record<string, unknown>): Promise<OpenAICompletion>;
+}
+interface OpenAIChat {
+    completions: OpenAIChatCompletions;
+}
+interface OpenAILike {
+    chat: OpenAIChat;
+    [key: string]: unknown;
+}
+interface OpenAIWrapperOptions extends Analytix402Config {
+    /**
+     * Override cost table (USD per 1 million tokens).
+     * Keys are model names; values have `input` and `output` fields.
+     */
+    costPerMillionTokens?: Record<string, {
+        input: number;
+        output: number;
+    }>;
+}
+/**
+ * Wrap an OpenAI SDK instance to auto-track LLM usage via Analytix402.
+ *
+ * Returns a proxied instance — the original is not mutated.
+ */
+declare function withAnalytix<T extends OpenAILike>(openai: T, options: OpenAIWrapperOptions): T;
+/**
+ * Access the Analytix402 client from a wrapped OpenAI instance.
+ */
+declare function getAnalytixClient(openai: OpenAILike): Analytix402Client | undefined;
+
+export { type OpenAIWrapperOptions, getAnalytixClient, withAnalytix };