@analytix402/sdk 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @analytix402/sdk
+
+Monitor, secure, and optimize your x402 APIs. Drop-in Express middleware that captures requests, payments, and performance data — viewable on [analytix402.com](https://analytix402.com).
+
+## Installation
+
+```bash
+npm install @analytix402/sdk
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { Analytix402 } from '@analytix402/sdk';
+
+const app = express();
+
+// Add Analytix402 middleware (before your routes)
+app.use(Analytix402({
+  apiKey: 'ax_live_your_key_here',
+}));
+
+// Your x402 routes
+app.get('/api/data', (req, res) => {
+  res.json({ data: 'Hello World' });
+});
+
+app.listen(3000);
+```
+
+That's it! Revenue, requests, and security data will appear in your [Analytix402 dashboard](https://analytix402.com/dashboard.html).
+
+## What Gets Tracked
+
+The SDK automatically captures:
+
+- **Request data**: Method, path, status code, response time
+- **Payment data**: Amount, currency, payer wallet (from x402 headers)
+- **Metadata**: IP address, user agent, timestamp
+
+All data is batched and sent asynchronously — your API response times are not affected.
+
+## Configuration
+
+```typescript
+app.use(Analytix402({
+  // Required: Your API key from the Analytix402 dashboard
+  apiKey: 'ax_live_xxxxx',
+
+  // Optional: Custom API endpoint (for self-hosted)
+  baseUrl: 'https://api.analytix402.com',
+
+  // Optional: Enable debug logging
+  debug: false,
+
+  // Optional: Batch size before sending (default: 100)
+  batchSize: 100,
+
+  // Optional: Flush interval in ms (default: 5000)
+  flushInterval: 5000,
+
+  // Optional: Max retries for failed requests (default: 3)
+  maxRetries: 3,
+
+  // Optional: Max events to queue offline (default: 1000)
+  maxQueueSize: 1000,
+
+  // Optional: Request timeout in ms (default: 10000)
+  timeout: 10000,
+
+  // Optional: Paths to exclude from tracking
+  excludePaths: ['/health', '/internal/*'],
+
+  // Optional: Custom endpoint naming
+  getEndpointName: (req) => {
+    // Group by route pattern instead of full path
+    return req.path.replace(/\/[0-9a-f-]+/g, '/:id');
+  },
+
+  // Optional: Custom filtering
+  shouldTrack: (req) => {
+    // Only track API routes
+    return req.path.startsWith('/api/');
+  },
+}));
+```
+
+## x402 Payment Headers
+
+The SDK automatically reads these headers set by x402 facilitators:
+
+| Header | Description |
+|--------|-------------|
+| `x-payment` | Payment receipt/proof |
+| `x-payment-token` | Payment JWT |
+| `x-payer` | Payer wallet address |
+| `x-payment-amount` | Payment amount |
+| `x-payment-currency` | Currency (e.g., USDC) |
+| `x-payment-tx` | Transaction hash |
+| `x-facilitator` | Facilitator URL |
+
+## Default Excluded Paths
+
+These paths are excluded from tracking by default:
+
+`/health`, `/healthz`, `/ready`, `/readyz`, `/live`, `/livez`, `/metrics`, `/favicon.ico`, `/.well-known`
+
+## Manual Tracking
+
+For non-Express frameworks or custom tracking:
+
+```typescript
+import { createAnalytix402Client } from '@analytix402/sdk';
+
+const client = createAnalytix402Client({
+  apiKey: 'ax_live_xxxxx',
+});
+
+// Track a custom event
+client.track({
+  type: 'request',
+  method: 'GET',
+  path: '/api/data',
+  statusCode: 200,
+  responseTimeMs: 45,
+  timestamp: new Date().toISOString(),
+  payment: {
+    amount: '0.01',
+    currency: 'USDC',
+    wallet: '0x8f2a...',
+    status: 'success',
+  },
+});
+
+// Flush events before shutdown
+await client.flush();
+
+// Graceful shutdown
+await client.shutdown();
+```
+
+## Performance
+
+- **< 50ms overhead** per request
+- Events are batched and sent asynchronously
+- Automatic retry with exponential backoff
+- Offline queue (up to 1000 events)
+- Non-blocking — your API never waits for Analytix402
+
+## Requirements
+
+- Node.js 18+
+- Express 4.x or 5.x (for middleware, optional)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,236 @@
+/**
+ * Analytix402 SDK Types
+ */
+interface Analytix402Config {
+    /**
+     * Your Analytix402 API key (starts with ax_live_ or ax_test_)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Analytix402 API
+     * @default "https://api.analytix402.com"
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Maximum number of events to batch before sending
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Maximum time (ms) to wait before flushing events
+     * @default 5000
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Maximum events to queue when offline
+     * @default 1000
+     */
+    maxQueueSize?: number;
+    /**
+     * Request timeout in milliseconds
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * Paths to exclude from tracking (supports wildcards)
+     * @default ["/health", "/healthz", "/ready", "/metrics"]
+     */
+    excludePaths?: string[];
+    /**
+     * Custom function to extract endpoint name from request
+     */
+    getEndpointName?: (req: RequestInfo) => string;
+    /**
+     * Custom function to determine if request should be tracked
+     */
+    shouldTrack?: (req: RequestInfo) => boolean;
+    /**
+     * Agent identifier for multi-agent tracking
+     */
+    agentId?: string;
+    /**
+     * Agent friendly name
+     */
+    agentName?: string;
+}
+interface RequestEvent {
+    type: 'request';
+    method: string;
+    path: string;
+    endpoint?: string;
+    statusCode: number;
+    responseTimeMs: number;
+    payment?: PaymentInfo;
+    /** Agent identifier */
+    agentId?: string;
+    /** Task identifier for grouping actions */
+    taskId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+    ip?: string;
+    userAgent?: string;
+}
+interface PaymentInfo {
+    /** Payment amount */
+    amount: string;
+    /** Currency (e.g., "USDC") */
+    currency: string;
+    /** Payer wallet address */
+    wallet: string;
+    /** Payment status */
+    status: 'success' | 'failed' | 'pending';
+    /** Transaction hash if available */
+    txHash?: string;
+    /** Facilitator URL */
+    facilitator?: string;
+}
+interface HeartbeatEvent {
+    type: 'heartbeat';
+    agentId: string;
+    status: 'healthy' | 'degraded' | 'error';
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface TaskOutcome {
+    type: 'task_outcome';
+    agentId?: string;
+    taskId: string;
+    success: boolean;
+    durationMs?: number;
+    cost?: number;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface LLMUsageEvent {
+    type: 'llm_usage';
+    agentId?: string;
+    taskId?: string;
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd?: number;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface BatchPayload {
+    events: (RequestEvent | HeartbeatEvent | TaskOutcome | LLMUsageEvent)[];
+    sdk: {
+        name: string;
+        version: string;
+    };
+    sentAt: string;
+}
+interface RequestInfo {
+    method: string;
+    path: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+}
+interface ResponseInfo {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface Analytix402Client {
+    /**
+     * Track a request event
+     */
+    track(event: RequestEvent): void;
+    /**
+     * Flush all queued events immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the client gracefully
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Send a heartbeat signal
+     */
+    heartbeat(status?: 'healthy' | 'degraded' | 'error', metadata?: Record<string, unknown>): void;
+    /**
+     * Report a task outcome
+     */
+    reportOutcome(taskId: string, success: boolean, options?: {
+        durationMs?: number;
+        cost?: number;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Start a task and return a task tracker
+     */
+    startTask(taskId?: string): TaskTracker;
+    /** Track LLM token usage */
+    trackLLM(usage: {
+        model: string;
+        provider: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd?: number;
+        durationMs?: number;
+        taskId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+}
+interface TaskTracker {
+    taskId: string;
+    /** End the task and report outcome */
+    end(success: boolean, metadata?: Record<string, unknown>): void;
+}
+interface ExpressRequest {
+    method: string;
+    path: string;
+    originalUrl: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    get(name: string): string | undefined;
+}
+interface ExpressResponse {
+    statusCode: number;
+    getHeader(name: string): string | number | string[] | undefined;
+    on(event: string, callback: () => void): void;
+}
+type ExpressNextFunction = (err?: unknown) => void;
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+
+/**
+ * Analytix402 Express Middleware
+ * Captures requests and x402 payment data
+ */
+
+/**
+ * Create Express middleware for Analytix402
+ */
+declare function analytix402(config: Analytix402Config): ExpressMiddleware;
+/**
+ * Create Express middleware (alias for analytix402)
+ */
+declare const Analytix402: typeof analytix402;
+/**
+ * Get the underlying client for manual tracking
+ */
+declare function createAnalytix402Client(config: Analytix402Config): Analytix402Client;
+
+/**
+ * Analytix402 Client
+ * Handles event batching, queuing, and transmission
+ */
+
+declare function createClient(config: Analytix402Config): Analytix402Client;
+
+export { Analytix402, type Analytix402Client, type Analytix402Config, type BatchPayload, type ExpressMiddleware, type ExpressNextFunction, type ExpressRequest, type ExpressResponse, type HeartbeatEvent, type LLMUsageEvent, type PaymentInfo, type RequestEvent, type RequestInfo, type ResponseInfo, type TaskOutcome, type TaskTracker, analytix402, createAnalytix402Client, createClient };

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Analytix402 SDK Types
+ */
+interface Analytix402Config {
+    /**
+     * Your Analytix402 API key (starts with ax_live_ or ax_test_)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Analytix402 API
+     * @default "https://api.analytix402.com"
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Maximum number of events to batch before sending
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Maximum time (ms) to wait before flushing events
+     * @default 5000
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Maximum events to queue when offline
+     * @default 1000
+     */
+    maxQueueSize?: number;
+    /**
+     * Request timeout in milliseconds
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * Paths to exclude from tracking (supports wildcards)
+     * @default ["/health", "/healthz", "/ready", "/metrics"]
+     */
+    excludePaths?: string[];
+    /**
+     * Custom function to extract endpoint name from request
+     */
+    getEndpointName?: (req: RequestInfo) => string;
+    /**
+     * Custom function to determine if request should be tracked
+     */
+    shouldTrack?: (req: RequestInfo) => boolean;
+    /**
+     * Agent identifier for multi-agent tracking
+     */
+    agentId?: string;
+    /**
+     * Agent friendly name
+     */
+    agentName?: string;
+}
+interface RequestEvent {
+    type: 'request';
+    method: string;
+    path: string;
+    endpoint?: string;
+    statusCode: number;
+    responseTimeMs: number;
+    payment?: PaymentInfo;
+    /** Agent identifier */
+    agentId?: string;
+    /** Task identifier for grouping actions */
+    taskId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+    ip?: string;
+    userAgent?: string;
+}
+interface PaymentInfo {
+    /** Payment amount */
+    amount: string;
+    /** Currency (e.g., "USDC") */
+    currency: string;
+    /** Payer wallet address */
+    wallet: string;
+    /** Payment status */
+    status: 'success' | 'failed' | 'pending';
+    /** Transaction hash if available */
+    txHash?: string;
+    /** Facilitator URL */
+    facilitator?: string;
+}
+interface HeartbeatEvent {
+    type: 'heartbeat';
+    agentId: string;
+    status: 'healthy' | 'degraded' | 'error';
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface TaskOutcome {
+    type: 'task_outcome';
+    agentId?: string;
+    taskId: string;
+    success: boolean;
+    durationMs?: number;
+    cost?: number;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface LLMUsageEvent {
+    type: 'llm_usage';
+    agentId?: string;
+    taskId?: string;
+    model: string;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd?: number;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface BatchPayload {
+    events: (RequestEvent | HeartbeatEvent | TaskOutcome | LLMUsageEvent)[];
+    sdk: {
+        name: string;
+        version: string;
+    };
+    sentAt: string;
+}
+interface RequestInfo {
+    method: string;
+    path: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+}
+interface ResponseInfo {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface Analytix402Client {
+    /**
+     * Track a request event
+     */
+    track(event: RequestEvent): void;
+    /**
+     * Flush all queued events immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the client gracefully
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Send a heartbeat signal
+     */
+    heartbeat(status?: 'healthy' | 'degraded' | 'error', metadata?: Record<string, unknown>): void;
+    /**
+     * Report a task outcome
+     */
+    reportOutcome(taskId: string, success: boolean, options?: {
+        durationMs?: number;
+        cost?: number;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Start a task and return a task tracker
+     */
+    startTask(taskId?: string): TaskTracker;
+    /** Track LLM token usage */
+    trackLLM(usage: {
+        model: string;
+        provider: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd?: number;
+        durationMs?: number;
+        taskId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+}
+interface TaskTracker {
+    taskId: string;
+    /** End the task and report outcome */
+    end(success: boolean, metadata?: Record<string, unknown>): void;
+}
+interface ExpressRequest {
+    method: string;
+    path: string;
+    originalUrl: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    get(name: string): string | undefined;
+}
+interface ExpressResponse {
+    statusCode: number;
+    getHeader(name: string): string | number | string[] | undefined;
+    on(event: string, callback: () => void): void;
+}
+type ExpressNextFunction = (err?: unknown) => void;
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+
+/**
+ * Analytix402 Express Middleware
+ * Captures requests and x402 payment data
+ */
+
+/**
+ * Create Express middleware for Analytix402
+ */
+declare function analytix402(config: Analytix402Config): ExpressMiddleware;
+/**
+ * Create Express middleware (alias for analytix402)
+ */
+declare const Analytix402: typeof analytix402;
+/**
+ * Get the underlying client for manual tracking
+ */
+declare function createAnalytix402Client(config: Analytix402Config): Analytix402Client;
+
+/**
+ * Analytix402 Client
+ * Handles event batching, queuing, and transmission
+ */
+
+declare function createClient(config: Analytix402Config): Analytix402Client;
+
+export { Analytix402, type Analytix402Client, type Analytix402Config, type BatchPayload, type ExpressMiddleware, type ExpressNextFunction, type ExpressRequest, type ExpressResponse, type HeartbeatEvent, type LLMUsageEvent, type PaymentInfo, type RequestEvent, type RequestInfo, type ResponseInfo, type TaskOutcome, type TaskTracker, analytix402, createAnalytix402Client, createClient };