@aispendguard/sdk 0.1.0 → 0.1.2

package/README.md

@@ -133,6 +133,63 @@ const event = createGeminiUsageEvent({
 await trackUsage(event);
 ```
 
+## Streaming Responses
+
+With streaming, usage data arrives in the **final chunk**. Accumulate the stream, then track:
+
+### OpenAI Streaming
+```ts
+const startedAt = Date.now();
+const stream = await openai.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Hello" }],
+  stream: true,
+  stream_options: { include_usage: true }, // required for usage in stream
+});
+
+let usage;
+for await (const chunk of stream) {
+  if (chunk.usage) usage = chunk.usage;
+  // ... process chunk.choices[0]?.delta
+}
+
+if (usage) {
+  const event = createOpenAIUsageEvent({
+    model: "gpt-4o-mini",
+    usage,
+    latencyMs: Date.now() - startedAt,
+    tags: { task_type: "chat", feature: "assistant", route: "POST /api/chat" },
+  });
+  await trackUsage(event);
+}
+```
+
+### Anthropic Streaming
+```ts
+const startedAt = Date.now();
+const stream = anthropic.messages.stream({
+  model: "claude-sonnet-4-20250514",
+  messages: [{ role: "user", content: "Hello" }],
+  max_tokens: 200,
+});
+
+for await (const event of stream) {
+  // ... process text events
+}
+
+const message = await stream.finalMessage();
+
+const event = createAnthropicUsageEvent({
+  model: "claude-sonnet-4-20250514",
+  usage: message.usage,
+  latencyMs: Date.now() - startedAt,
+  tags: { task_type: "chat", feature: "assistant", route: "POST /api/chat" },
+});
+await trackUsage(event);
+```
+
+> **Key point:** OpenAI requires `stream_options: { include_usage: true }` — without it, usage is `null` in the stream. Anthropic provides usage on the final message automatically.
+
 ## API
 - `init(config)`
 - `trackUsage(event | event[])`

package/dist/client.js

@@ -38,7 +38,7 @@ class AISpendGuardClient {
             if (this.strict) {
                 throw error;
             }
-            this.logger.warn(`[aispendguard-sdk] ${message}`);
+            this.logger.warn(`[aispendguard-sdk] tracking failed: ${message}. Use { strict: true } to throw on errors.`);
             return { ok: false, error: message };
         }
     }
@@ -74,16 +74,28 @@ class AISpendGuardClient {
                 body: JSON.stringify(payload),
                 signal: controller.signal
             });
+            if (response.redirected) {
+                throw new Error(`ingest failed: redirected to ${response.url} — update your endpoint to "${response.url}"`);
+            }
             const raw = (await response.json().catch(() => null));
             if (!response.ok) {
-                const msg = raw?.errors?.join("; ") || `HTTP ${response.status}`;
-                throw new Error(`ingest failed: ${msg}`);
+                const msg = raw?.errors?.join("; ") || `HTTP ${response.status} ${response.statusText}`;
+                throw new Error(`ingest failed (${this.endpoint}): ${msg}`);
             }
             if (!raw) {
                 throw new Error("ingest failed: empty response body");
             }
             return raw;
         }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new Error(`ingest failed: request to ${this.endpoint} timed out after ${this.timeoutMs}ms`);
+            }
+            if (err instanceof TypeError) {
+                throw new Error(`ingest failed: network error reaching ${this.endpoint} — ${err.message}`);
+            }
+            throw err;
+        }
         finally {
             clearTimeout(timeout);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aispendguard/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Tags-only SDK for tracking AI API spend with AISpendGuard. Supports OpenAI, Anthropic, Google Gemini, LangChain.js, and OpenTelemetry.",
   "license": "MIT",
   "main": "dist/index.js",