@fluxgate/sdk 0.0.2-dev.0 → 0.0.3-dev.0

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export declare class FluxGate {
     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";
+export type { LLMEvent, CreateAiEventResponse, TrackedUser, AiEventMetadata, AiEventStatus, AiEventUsage, Performance, CostOverride, ExtractedUsage, FluxGateCostTrackingResponse, WithTracking, FluxGateConfig, } from "./types/types.js";

package/dist/index.js

@@ -19,9 +19,6 @@ export class FluxGate {
         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: {
@@ -46,13 +43,7 @@ export class FluxGate {
             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;
+            return null;
         }
         let trackingData = null;
         try {

package/dist/index.test.js

@@ -45,28 +45,23 @@ describe("FluxGate", () => {
     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,
+                recordId: "event-123",
+                totalTokens: 150,
+                totalCost: 0.001,
+                status: "ok",
             };
             vi.mocked(fetch).mockResolvedValue({
-                status: 200,
-                statusText: "OK",
+                status: 201,
+                statusText: "Created",
                 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",
-                },
+                provider: "openai",
+                model: "gpt-4",
+                feature: "chat",
+                user: "user-123",
+                performance: { latency: 1000, status: "SUCCESS", isStreamed: false },
+                usage: { promptTokens: 100, completionTokens: 50 },
             };
             const result = await instance.recordEvent(event);
             expect(fetch).toHaveBeenCalledWith(mockEndpoint, expect.objectContaining({
@@ -80,26 +75,27 @@ describe("FluxGate", () => {
             }));
             expect(result).toEqual(mockResponse);
         });
-        it("should default status to SUCCESS if not provided", async () => {
+        it("should send event body unchanged to the API", async () => {
             vi.mocked(fetch).mockResolvedValue({
                 status: 200,
                 statusText: "OK",
                 text: async () => JSON.stringify({
-                    id: "123",
-                    createdAt: "2026-05-05T00:00:00Z",
-                    cost: 0.001,
+                    recordId: "123",
+                    totalTokens: 150,
+                    totalCost: 0.001,
+                    status: "ok",
                 }),
             });
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 50,
-                },
+                provider: "openai",
+                model: "gpt-4o",
+                performance: { latency: 500, status: "SUCCESS", isStreamed: false },
+                usage: { promptTokens: 100, completionTokens: 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");
+            expect(body).toEqual(event);
         });
         it("should handle fetch errors gracefully", async () => {
             const mockResponse = {
@@ -113,10 +109,10 @@ describe("FluxGate", () => {
                 text: async () => JSON.stringify(mockResponse),
             });
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 50,
-                },
+                provider: "openai",
+                model: "gpt-4o",
+                performance: { latency: 500, status: "SUCCESS", isStreamed: false },
+                usage: { promptTokens: 100, completionTokens: 50 },
             };
             const result = await instance.recordEvent(event);
             expect(result).toEqual(mockResponse);
@@ -128,10 +124,10 @@ describe("FluxGate", () => {
                 text: async () => "invalid json",
             });
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 50,
-                },
+                provider: "openai",
+                model: "gpt-4o",
+                performance: { latency: 500, status: "SUCCESS", isStreamed: false },
+                usage: { promptTokens: 100, completionTokens: 50 },
             };
             const result = await instance.recordEvent(event);
             expect(result).toBeNull();
@@ -150,12 +146,12 @@ describe("FluxGate", () => {
                 }), 1000);
             }));
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 50,
-                },
+                provider: "openai",
+                model: "gpt-4o",
+                performance: { latency: 500, status: "SUCCESS", isStreamed: false },
+                usage: { promptTokens: 100, completionTokens: 50 },
             };
-            await expect(shortTimeoutTracker.recordEvent(event)).resolves.toHaveProperty("status", "ERROR");
+            await expect(shortTimeoutTracker.recordEvent(event)).resolves.toBeNull();
         });
         it("should include complex metadata in the event", async () => {
             vi.mocked(fetch).mockResolvedValue({
@@ -168,30 +164,26 @@ describe("FluxGate", () => {
                 }),
             });
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 50,
-                    cachedTokens: 20,
-                    model: "gpt-4",
-                    provider: "openai",
-                    latencyInMs: 1500,
-                    isStreamed: true,
-                    streamingDurationInMs: 2000,
+                provider: "openai",
+                model: "gpt-4",
+                feature: "chat",
+                step: "generation",
+                user: {
+                    id: "user-123",
+                    name: "Test User",
+                    email: "test@example.com",
+                    monthlyRevenue: "99.99",
                 },
-                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",
+                sessionId: "session-456",
+                conversationId: "conv-789",
+                performance: {
+                    latency: 1500,
+                    status: "SUCCESS",
+                    isStreamed: true,
+                    streamDuration: 2000,
                 },
+                usage: { promptTokens: 100, completionTokens: 50, cacheReadTokens: 20 },
+                metadata: { customField: "custom value" },
             };
             await instance.recordEvent(event);
             const callArgs = vi.mocked(fetch).mock.calls[0];
@@ -210,19 +202,21 @@ describe("FluxGate", () => {
                 }),
             });
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 0,
-                },
-                status: {
+                provider: "openai",
+                model: "gpt-4o",
+                performance: {
+                    latency: 500,
                     status: "ERROR",
+                    isStreamed: false,
                     errorMessage: "API call failed",
                 },
+                usage: { promptTokens: 100, completionTokens: 0 },
             };
             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);
+            expect(body.performance.status).toEqual("ERROR");
+            expect(body.performance.errorMessage).toEqual("API call failed");
         });
     });
     describe("debug mode", () => {
@@ -244,10 +238,10 @@ describe("FluxGate", () => {
                 }),
             });
             const event = {
-                usage: {
-                    inputTokens: 100,
-                    outputTokens: 50,
-                },
+                provider: "openai",
+                model: "gpt-4o",
+                performance: { latency: 500, status: "SUCCESS", isStreamed: false },
+                usage: { promptTokens: 100, completionTokens: 50 },
             };
             await debugTracker.recordEvent(event);
             expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("[fluxgate] Sending event"), expect.any(String));

package/dist/types/types.d.ts

@@ -1,43 +1,89 @@
 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;
+    name?: string | null;
+    email?: string | null;
+    image?: string | null;
+    /** Monthly revenue in USD as a string (e.g. "99.99") */
+    monthlyRevenue?: number | string | null;
+};
+export type Performance = {
+    /** Total round-trip time in milliseconds from request start to final response closure */
+    latency: number;
+    /** HTTP status category returned by the provider */
+    status: "SUCCESS" | "ERROR" | "BLOCKED" | "MAX_TOKENS" | "CONTENT_FILTER" | "RECITATION" | "MALFORMED_REQUEST";
+    /** Whether the response was processed via SSE streaming */
+    isStreamed: boolean;
+    /** Active streaming connection duration in ms (Total Duration - TTFT). Null if not streamed or request failed. */
+    streamDuration?: number | null;
+    /** Raw error string if the request failed. Null/undefined if successful. */
+    errorMessage?: string | null;
 };
 export type AiEventUsage = {
-    inputTokens: number;
-    outputTokens: number;
-    cachedTokens?: number;
-    model?: string;
-    provider?: string;
-    latencyInMs?: number;
-    isStreamed?: boolean;
-    streamingDurationInMs?: number;
+    /** Fresh text tokens evaluated down the wire (input/prompt tokens) */
+    promptTokens: number;
+    /** Generation tokens sent back from the inference machine (output tokens) */
+    completionTokens: number;
+    /** Tokens read from a warm cache layer (e.g. OpenAI/Anthropic prompt caching) */
+    cacheReadTokens?: number | null;
+    /** Tokens written to initialize or refresh a cold cache block */
+    cacheWriteTokens?: number | null;
+    /** Internal thinking/reasoning tokens (e.g. OpenAI o1/o3, DeepSeek R1) */
+    reasoningTokens?: number | null;
 };
 export type AiEventMetadata = {
+    /** Service tiering mode affecting pricing multipliers */
+    serviceTier?: "default" | "standard" | "batch" | "flex" | "priority";
+    /** Explicit hosting region for regional price variance (e.g. AWS Bedrock / Google Vertex) */
+    region?: string;
+    /** Explicit total cost in USD from an aggregator proxy (e.g. OpenRouter, LiteLLM). Skips server-side cost computation. */
+    openrouterCost?: number;
+    /** Provider cache expiration window. Accepts "5m", "1h", or a custom string. */
+    cacheTtl?: string;
+    [key: string]: unknown;
+};
+export type CostOverride = {
+    /** Price per 1,000,000 base prompt tokens */
+    inputCostPer1MTokens: number;
+    /** Price per 1,000,000 baseline generation output tokens */
+    outputCostPer1MTokens: number;
+    /** Surcharge rate for writing/saving a prompt segment to cache */
+    cacheWriteCostPer1MTokens?: number | null;
+    /** Discounted rate for reading from a warm prompt segment cache */
+    cacheReadCostPer1MTokens?: number | null;
+    /** Customized rate for isolated reasoning execution blocks */
+    reasoningCostPer1MTokens?: number | null;
+};
+export type LLMEvent = {
+    /** AI provider identifier (e.g. "openai", "anthropic", "google", "xai", "deepseek") */
+    provider: string;
+    /** Model identifier (e.g. "gpt-4o", "claude-opus-4", "gemini-2.0-flash") */
+    model: string;
+    /** End-user who triggered the event — either a plain string ID or a TrackedUser object */
+    user?: string | TrackedUser;
+    /** Product feature name (e.g. "chat", "summarization", "embedding") */
     feature?: string;
     step?: string;
-    user?: string | TrackedUser;
     sessionId?: string;
     conversationId?: string;
-    timestamp?: Date;
-    [key: string]: unknown;
-};
-export type LLMEvent = {
+    /** Unix timestamp in milliseconds. Defaults to server ingest time if omitted. */
+    timestamp?: number;
+    performance: Performance;
     usage: AiEventUsage;
-    status?: AiEventStatus | {
-        status: AiEventStatus;
-        errorMessage?: string;
-    };
     metadata?: AiEventMetadata;
+    costOverride?: CostOverride;
 };
 export type CreateAiEventResponse = {
-    id: string;
-    createdAt: string;
-    cost: number | null;
-    status: "SUCCESS" | "ERROR";
+    /** ID of the persisted AiEvent record */
+    recordId: string;
+    /** Sum of all token categories */
+    totalTokens: number;
+    /** Computed total cost in USD. Null when no pricing data is available. */
+    totalCost: number | null;
+    /** ok — cost was successfully computed; no_pricing — model/provider not in pricing table */
+    status: "ok" | "no_pricing";
+    /** Human-readable explanation of how the cost was derived */
+    description?: string;
 };
 export interface FluxGateConfig {
     apiKey: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxgate/sdk",
-  "version": "0.0.2-dev.0",
+  "version": "0.0.3-dev.0",
   "description": "Core tracking SDK for FluxGate token usage, latency, and cost monitoring.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",