@fluxgate/sdk 0.0.2-dev.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 [Your Name or Organization]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# @fluxgate/sdk
+
+![Status: In Development](https://img.shields.io/badge/status-in%20development-orange)
+
+Core tracking functionality for FluxGate. This package provides the base `FluxGate` class that sends usage data to the FluxGate API.
+
+## 📦 Installation
+
+```bash
+npm install @fluxgate/sdk
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { FluxGate } from "@fluxgate/sdk";
+
+const fluxgate = new FluxGate({
+  apiKey: process.env.FLUXGATE_API_KEY,
+  endpoint: "https://fluxgate.app/api/events", // optional
+  timeout: 5000, // optional, default: 5000ms
+  debug: false, // optional, default: false
+});
+
+// Record a usage event
+const response = await fluxgate.recordEvent({
+  usage: {
+    inputTokens: 100,
+    outputTokens: 50,
+    cachedTokens: 20,
+    model: "gpt-4",
+    provider: "openai",
+    latencyInMs: 1500,
+    isStreamed: false,
+  },
+  status: "SUCCESS",
+  metadata: {
+    feature: "chatbot",
+    user: "user-123",
+    sessionId: "session-456",
+  },
+});
+
+console.log(response);
+// { id: "event-123", createdAt: "2026-05-05T...", cost: 0.001 }
+```
+
+## 📖 API Reference
+
+### `FluxGate`
+
+The main class for tracking LLM usage events.
+
+#### Constructor
+
+```typescript
+new FluxGate(config: FluxGateConfig)
+```
+
+**Configuration Options:**
+
+| Option     | Type      | Required | Default                           | Description                     |
+| ---------- | --------- | -------- | --------------------------------- | ------------------------------- |
+| `apiKey`   | `string`  | ✅       | -                                 | Your FluxGate API key           |
+| `endpoint` | `string`  | ❌       | `https://fluxgate.app/api/events` | API endpoint URL                |
+| `timeout`  | `number`  | ❌       | `5000`                            | Request timeout in milliseconds |
+| `debug`    | `boolean` | ❌       | `false`                           | Enable debug logging            |
+
+#### Methods
+
+##### `recordEvent(event: LLMEvent)`
+
+Records a usage event to FluxGate.
+
+**Parameters:**
+
+```typescript
+interface LLMEvent {
+  usage: AiEventUsage;
+  status?: AiEventStatus | { status: AiEventStatus; errorMessage?: string };
+  metadata?: AiEventMetadata;
+}
+```
+
+**Usage Object:**
+
+```typescript
+interface AiEventUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens?: number;
+  model?: string;
+  provider?: string;
+  latencyInMs?: number;
+  isStreamed?: boolean;
+  streamingDurationInMs?: number;
+}
+```
+
+**Status Types:**
+
+```typescript
+type AiEventStatus =
+  | "SUCCESS"
+  | "ERROR"
+  | "BLOCKED"
+  | "MAX_TOKENS"
+  | "CONTENT_FILTER"
+  | "RECITATION"
+  | "MALFORMED_REQUEST";
+```
+
+**Metadata Object:**
+
+```typescript
+interface AiEventMetadata {
+  feature?: string;
+  step?: string;
+  user?: string | TrackedUser;
+  sessionId?: string;
+  conversationId?: string;
+  [key: string]: unknown; // Custom fields allowed
+}
+
+interface TrackedUser {
+  id: string;
+  name?: string;
+  email?: string;
+  image?: string;
+  monthlyRevenue?: number;
+}
+```
+
+**Returns:**
+
+```typescript
+Promise<CreateAiEventResponse | null>;
+
+interface CreateAiEventResponse {
+  id: string;
+  createdAt: string;
+  cost: number | null;
+}
+```
+
+## 💡 Usage Examples
+
+### Basic Usage
+
+```typescript
+const fluxgate = new FluxGate({
+  apiKey: "your-api-key",
+});
+
+await fluxgate.recordEvent({
+  usage: {
+    inputTokens: 100,
+    outputTokens: 50,
+  },
+  status: "SUCCESS",
+});
+```
+
+### With Full Metadata
+
+```typescript
+await fluxgate.recordEvent({
+  usage: {
+    inputTokens: 200,
+    outputTokens: 150,
+    cachedTokens: 50,
+    model: "gpt-4-turbo",
+    provider: "openai",
+    latencyInMs: 2500,
+    isStreamed: true,
+    streamingDurationInMs: 3000,
+  },
+  status: "SUCCESS",
+  metadata: {
+    feature: "code-generation",
+    step: "implementation",
+    user: {
+      id: "user-123",
+      name: "John Doe",
+      email: "john@example.com",
+      monthlyRevenue: 99.99,
+    },
+    sessionId: "session-abc",
+    conversationId: "conv-xyz",
+    customField: "any custom data",
+  },
+});
+```
+
+### Error Tracking
+
+```typescript
+await fluxgate.recordEvent({
+  usage: {
+    inputTokens: 100,
+    outputTokens: 0,
+  },
+  status: {
+    status: "ERROR",
+    errorMessage: "API rate limit exceeded",
+  },
+  metadata: {
+    feature: "chatbot",
+  },
+});
+```
+
+### With Debug Mode
+
+```typescript
+const fluxgate = new FluxGate({
+  apiKey: "your-api-key",
+  debug: true, // Logs all events to console
+});
+
+await fluxgate.recordEvent({
+  usage: {
+    inputTokens: 100,
+    outputTokens: 50,
+  },
+});
+// [fluxgate] FluxGate initialized { endpoint: '...', timeout: 5000 }
+// [fluxgate] Sending event to ...: { ... }
+// [fluxgate] Event sent successfully. Status: 200. Response: { "id": "evt_...", ... }
+```
+
+### Custom Endpoint
+
+```typescript
+const fluxgate = new FluxGate({
+  apiKey: "your-api-key",
+  endpoint: "https://your-custom-domain.com/api/track",
+  timeout: 10000,
+});
+```
+
+## 🔧 Advanced Usage
+
+### Using with SDK Wrappers
+
+This package is typically used through provider-specific wrappers:
+
+- [`@fluxgate/openai`](../openai/README.md) - For OpenAI
+- [`@fluxgate/gemini`](../gemini/README.md) - For Google Gemini
+- [`@fluxgate/anthropic`](../anthropic/README.md) - For Anthropic
+
+### Direct Integration
+
+If you're integrating a custom provider:
+
+```typescript
+import { FluxGate, type LLMEvent } from "@fluxgate/sdk";
+
+const fluxgate = new FluxGate({ apiKey: "your-api-key" });
+
+async function trackMyCustomLLM(prompt: string) {
+  const start = performance.now();
+
+  try {
+    const response = await myCustomLLM.generate(prompt);
+
+    await fluxgate.recordEvent({
+      usage: {
+        inputTokens: response.inputTokens,
+        outputTokens: response.outputTokens,
+        model: "custom-model",
+        provider: "custom-provider",
+        latencyInMs: performance.now() - start,
+      },
+      status: "SUCCESS",
+      metadata: {
+        feature: "my-feature",
+      },
+    });
+
+    return response;
+  } catch (error) {
+    await fluxgate.recordEvent({
+      usage: {
+        inputTokens: 0,
+        outputTokens: 0,
+      },
+      status: {
+        status: "ERROR",
+        errorMessage: error.message,
+      },
+    });
+    throw error;
+  }
+}
+```
+
+## 🛡️ Error Handling
+
+The tracker is designed to never break your application:
+
+- Network errors are caught and logged (in debug mode)
+- Timeouts are handled gracefully
+- Returns `null` if tracking fails
+- Your main LLM calls continue regardless of tracking status
+
+```typescript
+const result = await tracker.recordEvent(event);
+if (result === null) {
+  // Tracking failed, but your app continues
+  console.log("Failed to track event");
+}
+```
+
+## 📊 Type Exports
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  LLMEvent,
+  CreateAiEventResponse,
+  TrackedUser,
+  AiEventMetadata,
+  FluxGateCostTrackingResponse,
+  WithTracking,
+  AiEventStatus,
+  AiEventUsage,
+  ExtractedUsage,
+  FluxGateConfig,
+} from "@fluxgate/sdk";
+```
+
+## 🔗 Related Packages
+
+- [@fluxgate/openai](../openai) - OpenAI SDK wrapper
+- [@fluxgate/gemini](../gemini) - Gemini SDK wrapper
+
+## 📝 License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { CreateAiEventResponse, LLMEvent, FluxGateConfig } from "./types/types.js";
+export declare class FluxGate {
+    private apiKey;
+    private endpoint;
+    private timeout;
+    private debug;
+    constructor(config: FluxGateConfig);
+    recordEvent(event: LLMEvent): Promise<CreateAiEventResponse | null>;
+}
+export type { LLMEvent, CreateAiEventResponse, TrackedUser, AiEventMetadata, FluxGateCostTrackingResponse, WithTracking, AiEventStatus, AiEventUsage, ExtractedUsage, FluxGateConfig, } from "./types/types.js";

package/dist/index.js

@@ -0,0 +1,72 @@
+export class FluxGate {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("FluxGate requires an apiKey in config");
+        }
+        this.apiKey = config.apiKey;
+        this.endpoint = config.endpoint || "https://fluxgate.app/api/events";
+        this.timeout = config.timeout || 5000;
+        this.debug = config.debug || false;
+        if (this.debug) {
+            console.log("[fluxgate] FluxGate initialized", {
+                endpoint: this.endpoint,
+                timeout: this.timeout,
+            });
+        }
+    }
+    async recordEvent(event) {
+        const controller = new AbortController();
+        if (this.debug) {
+            console.log(`[fluxgate] Sending event to ${this.endpoint}:`, JSON.stringify(event, null, 2));
+        }
+        if (!event.status) {
+            event.status = "SUCCESS";
+        }
+        const fetchPromise = fetch(this.endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+                "User-Agent": "@fluxgate/sdk/0.0.2-dev.0",
+            },
+            body: JSON.stringify(event),
+            signal: controller.signal,
+        });
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                controller.abort();
+                reject(new Error(`Request timeout after ${this.timeout}ms`));
+            }, this.timeout);
+        });
+        let response;
+        try {
+            response = await Promise.race([fetchPromise, timeoutPromise]);
+        }
+        catch (err) {
+            if (this.debug) {
+                console.error("[fluxgate] Network error sending event:", err);
+            }
+            return {
+                cost: 0,
+                createdAt: new Date().toISOString(),
+                id: "error-" + Math.random().toString(36).substring(2, 15),
+                status: "ERROR",
+            };
+            // throw err;
+        }
+        let trackingData = null;
+        try {
+            const text = await response.text();
+            trackingData = JSON.parse(text);
+        }
+        catch (error) {
+            if (this.debug) {
+                console.error("[fluxgate] Failed to parse response:", error);
+            }
+        }
+        if (this.debug) {
+            console.log(`[fluxgate] Event sent successfully. Status: ${response.status}. Response: ${JSON.stringify(trackingData)}`);
+        }
+        return trackingData;
+    }
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { FluxGate } from "./index.js";
+describe("FluxGate", () => {
+    let instance;
+    const mockApiKey = "test-api-key";
+    const mockEndpoint = "https://test.example.com/api/events";
+    // Mock fetch globally
+    const originalFetch = global.fetch;
+    beforeEach(() => {
+        instance = new FluxGate({
+            apiKey: mockApiKey,
+            endpoint: mockEndpoint,
+            timeout: 5000,
+            debug: false,
+        });
+        // Mock fetch
+        global.fetch = vi.fn();
+    });
+    afterEach(() => {
+        global.fetch = originalFetch;
+        vi.restoreAllMocks();
+    });
+    describe("constructor", () => {
+        it("should throw error if apiKey is not provided", () => {
+            expect(() => new FluxGate({
+                apiKey: "",
+            })).toThrow("FluxGate requires an apiKey in config");
+        });
+        it("should use default endpoint if not provided", () => {
+            const defaultTracker = new FluxGate({ apiKey: "test" });
+            expect(defaultTracker).toBeDefined();
+        });
+        it("should use custom endpoint if provided", () => {
+            const customTracker = new FluxGate({
+                apiKey: "test",
+                endpoint: "https://custom.example.com",
+            });
+            expect(customTracker).toBeDefined();
+        });
+        it("should use default timeout if not provided", () => {
+            const defaultTracker = new FluxGate({ apiKey: "test" });
+            expect(defaultTracker).toBeDefined();
+        });
+    });
+    describe("recordEvent", () => {
+        it("should send event to the correct endpoint", async () => {
+            const mockResponse = {
+                id: "event-123",
+                createdAt: "2026-05-05T00:00:00Z",
+                cost: 0.001,
+            };
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                statusText: "OK",
+                text: async () => JSON.stringify(mockResponse),
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                    model: "gpt-4",
+                    provider: "openai",
+                    latencyInMs: 1000,
+                },
+                status: "SUCCESS",
+                metadata: {
+                    feature: "chat",
+                    user: "user-123",
+                },
+            };
+            const result = await instance.recordEvent(event);
+            expect(fetch).toHaveBeenCalledWith(mockEndpoint, expect.objectContaining({
+                method: "POST",
+                headers: expect.objectContaining({
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${mockApiKey}`,
+                    "User-Agent": "@fluxgate/sdk/0.0.2-dev.0",
+                }),
+                body: JSON.stringify(event),
+            }));
+            expect(result).toEqual(mockResponse);
+        });
+        it("should default status to SUCCESS if not provided", async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                statusText: "OK",
+                text: async () => JSON.stringify({
+                    id: "123",
+                    createdAt: "2026-05-05T00:00:00Z",
+                    cost: 0.001,
+                }),
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                },
+            };
+            await instance.recordEvent(event);
+            const callArgs = vi.mocked(fetch).mock.calls[0];
+            const body = JSON.parse(callArgs[1]?.body);
+            expect(body.status).toBe("SUCCESS");
+        });
+        it("should handle fetch errors gracefully", async () => {
+            const mockResponse = {
+                id: "event-123",
+                createdAt: "2026-05-05T00:00:00Z",
+                cost: 0.001,
+            };
+            vi.mocked(fetch).mockResolvedValue({
+                status: 500,
+                statusText: "Internal Server Error",
+                text: async () => JSON.stringify(mockResponse),
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                },
+            };
+            const result = await instance.recordEvent(event);
+            expect(result).toEqual(mockResponse);
+        });
+        it("should handle invalid JSON response", async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                statusText: "OK",
+                text: async () => "invalid json",
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                },
+            };
+            const result = await instance.recordEvent(event);
+            expect(result).toBeNull();
+        });
+        it("should respect timeout setting", async () => {
+            const shortTimeoutTracker = new FluxGate({
+                apiKey: mockApiKey,
+                endpoint: mockEndpoint,
+                timeout: 100,
+            });
+            vi.mocked(fetch).mockImplementation(() => new Promise((resolve) => {
+                setTimeout(() => resolve({
+                    status: 200,
+                    statusText: "OK",
+                    text: async () => JSON.stringify({}),
+                }), 1000);
+            }));
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                },
+            };
+            await expect(shortTimeoutTracker.recordEvent(event)).resolves.toHaveProperty("status", "ERROR");
+        });
+        it("should include complex metadata in the event", async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                statusText: "OK",
+                text: async () => JSON.stringify({
+                    id: "123",
+                    createdAt: "2026-05-05T00:00:00Z",
+                    cost: 0.001,
+                }),
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                    cachedTokens: 20,
+                    model: "gpt-4",
+                    provider: "openai",
+                    latencyInMs: 1500,
+                    isStreamed: true,
+                    streamingDurationInMs: 2000,
+                },
+                status: "SUCCESS",
+                metadata: {
+                    feature: "chat",
+                    step: "generation",
+                    user: {
+                        id: "user-123",
+                        name: "Test User",
+                        email: "test@example.com",
+                        monthlyRevenue: 99.99,
+                    },
+                    sessionId: "session-456",
+                    conversationId: "conv-789",
+                    customField: "custom value",
+                },
+            };
+            await instance.recordEvent(event);
+            const callArgs = vi.mocked(fetch).mock.calls[0];
+            const body = JSON.parse(callArgs[1]?.body);
+            expect(body.usage).toEqual(event.usage);
+            expect(body.metadata).toEqual(event.metadata);
+        });
+        it("should handle status with error message", async () => {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                statusText: "OK",
+                text: async () => JSON.stringify({
+                    id: "123",
+                    createdAt: "2026-05-05T00:00:00Z",
+                    cost: null,
+                }),
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 0,
+                },
+                status: {
+                    status: "ERROR",
+                    errorMessage: "API call failed",
+                },
+            };
+            await instance.recordEvent(event);
+            const callArgs = vi.mocked(fetch).mock.calls[0];
+            const body = JSON.parse(callArgs[1]?.body);
+            expect(body.status).toEqual(event.status);
+        });
+    });
+    describe("debug mode", () => {
+        it("should log debug information when debug is enabled", async () => {
+            const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+            const debugTracker = new FluxGate({
+                apiKey: mockApiKey,
+                endpoint: mockEndpoint,
+                debug: true,
+            });
+            expect(consoleSpy).toHaveBeenCalledWith("[fluxgate] FluxGate initialized", expect.any(Object));
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                statusText: "OK",
+                text: async () => JSON.stringify({
+                    id: "123",
+                    createdAt: "2026-05-05T00:00:00Z",
+                    cost: 0.001,
+                }),
+            });
+            const event = {
+                usage: {
+                    inputTokens: 100,
+                    outputTokens: 50,
+                },
+            };
+            await debugTracker.recordEvent(event);
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("[fluxgate] Sending event"), expect.any(String));
+            consoleSpy.mockRestore();
+        });
+    });
+});

package/dist/types/types.d.ts

@@ -0,0 +1,63 @@
+export type AiEventStatus = "SUCCESS" | "ERROR" | "BLOCKED" | "MAX_TOKENS" | "CONTENT_FILTER" | "RECITATION" | "MALFORMED_REQUEST";
+export type TrackedUser = {
+    id: string;
+    name?: string;
+    email?: string;
+    image?: string;
+    monthlyRevenue?: number;
+};
+export type AiEventUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+    model?: string;
+    provider?: string;
+    latencyInMs?: number;
+    isStreamed?: boolean;
+    streamingDurationInMs?: number;
+};
+export type AiEventMetadata = {
+    feature?: string;
+    step?: string;
+    user?: string | TrackedUser;
+    sessionId?: string;
+    conversationId?: string;
+    timestamp?: Date;
+    [key: string]: unknown;
+};
+export type LLMEvent = {
+    usage: AiEventUsage;
+    status?: AiEventStatus | {
+        status: AiEventStatus;
+        errorMessage?: string;
+    };
+    metadata?: AiEventMetadata;
+};
+export type CreateAiEventResponse = {
+    id: string;
+    createdAt: string;
+    cost: number | null;
+    status: "SUCCESS" | "ERROR";
+};
+export interface FluxGateConfig {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+    timeout?: number;
+}
+export type FluxGateCostTrackingResponse = {
+    status: AiEventStatus;
+    cost: number | null;
+    trackingId: string | null;
+    createdAt: string | null;
+    errorMessage?: string;
+};
+export type WithTracking<T> = T & {
+    fluxGateCostTrackingResponse: FluxGateCostTrackingResponse;
+};
+export type ExtractedUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    totalTokens: number;
+};

package/dist/types/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@fluxgate/sdk",
+  "version": "0.0.2-dev.0",
+  "description": "Core tracking SDK for FluxGate token usage, latency, and cost monitoring.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./types": {
+      "types": "./dist/types/types.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../../",
+    "test:watch": "vitest --root ../../"
+  },
+  "keywords": [
+    "llm",
+    "tokens",
+    "tracker",
+    "openai",
+    "claude",
+    "gemini",
+    "monitoring",
+    "costs"
+  ],
+  "author": "FluxGate Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yehova73/fluxgate-npm.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/yehova73/fluxgate-npm/issues"
+  },
+  "homepage": "https://fluxgate.app",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}