@aisa-one/cli 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to `@aisa-one/cli` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.2] — 2026-08-03
+
+### Added
+
+- **`aisa balance` now queries the live account wallet through the API-key
+  balance endpoint.** It reports both the account balance and the amount
+  available to the current API key, with `--json` support for automation.
+
+### Fixed
+
+- **Skills registry now points at the canonical `agent-skills` repo.** The
+  `SKILLS_REPO` constant in `src/commands/skills.ts` was pinned to
+  `AIsa-team/OpenClaw-Skills`, which has been renamed to
+  `AIsa-team/agent-skills`. Every `aisa skills` subcommand kept working
+  only because GitHub serves a 301 redirect on the old slug; the constant
+  now references the canonical name so the registry no longer depends on
+  that redirect. ([#3](https://github.com/AIsa-team/cli/pull/3))
+- **`aisa skills list` and `aisa skills show` now render emojis for live
+  skills.** `parseSkillFrontmatter` only read `metadata.openclaw.emoji`,
+  but skills in `agent-skills` publish under `metadata.aisa.emoji`. The
+  parser now reads the new key first and falls back to the legacy
+  `openclaw` key for any older skills still in the wild.
+  ([#4](https://github.com/AIsa-team/cli/pull/4))
+
+### Changed
+
+- **`aisa skills init` templates aligned with `agent-skills` conventions.**
+  All six built-in scaffolds (`default`, `llm`, `search`, `finance`,
+  `twitter`, `video`) now emit:
+  - `homepage: https://aisa.one` (was `https://openclaw.ai`)
+  - `metadata.aisa.*` instead of `metadata.openclaw.*`
+  - `compatibility: ["openclaw", "claude-code", "hermes"]` to match the
+    shape used by `marketpulse`, `multi-source-search`,
+    `prediction-market-arbitrage`, and the rest of the live skills.
+
+  Skills scaffolded with `aisa skills init` will now render correctly in
+  the registry and pass review when contributed back upstream.
+  ([#5](https://github.com/AIsa-team/cli/pull/5))
+
+### Documentation
+
+- README Skills section now references
+  [`AIsa-team/agent-skills`](https://github.com/AIsa-team/agent-skills)
+  directly instead of the renamed `OpenClaw-Skills`.
+  ([#2](https://github.com/AIsa-team/cli/pull/2))
+
+## [0.2.0] — Initial public release
+
+- LLM gateway commands (`aisa chat`, `aisa models`).
+- API discovery and execution (`aisa run`, `aisa api …` WIP).
+- Web search (`aisa web-search`, `aisa scholar`).
+- Finance (`aisa stock`, `aisa crypto`, `aisa screener`).
+- Twitter/X (`aisa twitter …`, `aisa tweet`).
+- Video generation (`aisa video create|status`).
+- Skills registry (`aisa skills list|search|show|install|remove|init`).
+- MCP server auto-config (`aisa mcp setup|status`).
+- Config commands (`aisa config get|set|list|reset`) and auth
+  (`aisa login|logout|whoami`).
+
+[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/AIsa-team/cli/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/AIsa-team/cli/releases/tag/v0.2.1
+[0.2.0]: https://github.com/AIsa-team/cli/releases/tag/v0.2.0

package/README.md

@@ -47,14 +47,14 @@ aisa whoami               # Show auth status
 Chat with 70+ models (GPT, Claude, Gemini, Qwen, Deepseek, Grok) through a single OpenAI-compatible endpoint.
 
 ```bash
-aisa chat "your message" --model gpt-4.1
+aisa chat "your message" --model gpt-4.1-mini
 aisa chat "explain this" --model claude-opus-4-6 --stream
 aisa chat "respond in JSON" --model gemini-2.5-pro --json
 echo "summarize this" | aisa chat                        # pipe support
 
 aisa models                          # list all models
 aisa models --provider anthropic     # filter by provider
-aisa models show gpt-4.1             # model details
+aisa models show gpt-4.1-mini        # model details
 ```
 
 ### API Discovery & Execution
@@ -115,22 +115,23 @@ aisa video status <task-id>                      # check status
 ### Account
 
 ```bash
-aisa balance                # 🚧 WIP — check https://aisa.one/dashboard
+aisa balance                # Show wallet and API key credit balance
+aisa balance --json         # Output the balance response as JSON
 aisa usage --limit 20       # 🚧 WIP
 ```
 
 ## Skills
 
-Skills are markdown files that teach AI coding agents (Claude Code, Cursor, Copilot, etc.) how to use AISA APIs. Skills are sourced from the [OpenClaw-Skills](https://github.com/AIsa-team/OpenClaw-Skills) repository.
+Skills are markdown files that teach AI coding agents (Claude Code, Cursor, Copilot, etc.) how to use AISA APIs. Skills are sourced from the [agent-skills](https://github.com/AIsa-team/agent-skills) repository.
 
 ### Browse & Install
 
 ```bash
 aisa skills list                              # list all available skills
 aisa skills search "financial analysis"       # search by keyword
-aisa skills show market                       # show skill details
-aisa skills install market                     # install to agent directories
-aisa skills remove market                     # uninstall
+aisa skills show marketpulse                  # show skill details
+aisa skills install marketpulse               # install to agent directories
+aisa skills remove marketpulse                # uninstall
 ```
 
 Skills install to agent directories automatically:
@@ -155,7 +156,7 @@ aisa skills init my-skill --template llm           # LLM template
 
 Available templates: `default`, `llm`, `search`, `finance`, `twitter`, `video`
 
-To publish a skill, submit a pull request to [AIsa-team/OpenClaw-Skills](https://github.com/AIsa-team/OpenClaw-Skills).
+To publish a skill, submit a pull request to [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills).
 
 ## MCP Server
 
@@ -178,7 +179,7 @@ aisa config reset                               # reset to defaults
 ```
 
 Settings:
-- `defaultModel` — default model for `aisa chat` (default: `gpt-4.1`)
+- `defaultModel` — default model for `aisa chat` (default: `gpt-4.1-mini`)
 - `baseUrl` — API base URL (default: `https://api.aisa.one`)
 - `outputFormat` — output format: `text` or `json`
 

package/dist/api.d.ts

@@ -1,4 +1,3 @@
-import { type Response } from "node-fetch";
 import type { ApiResponse } from "./types.js";
 export interface RequestOptions {
     method?: "GET" | "POST" | "PUT" | "DELETE";

package/dist/api.js

@@ -1,4 +1,3 @@
-import fetch from "node-fetch";
 import { CLI_BASE_URL, APIS_BASE_URL } from "./constants.js";
 import { getConfig } from "./config.js";
 function getBaseUrl() {

package/dist/commands/account.d.ts

@@ -1,4 +1,7 @@
-export declare function balanceAction(): Promise<void>;
+export declare function formatMicrosUSD(micros: number | string | bigint): string;
+export declare function balanceAction(options?: {
+    json?: boolean;
+}): Promise<void>;
 export declare function usageAction(_options: {
     limit?: string;
     days?: string;

package/dist/commands/account.js

@@ -1,10 +1,38 @@
 import chalk from "chalk";
 import { requireApiKey } from "../config.js";
-import { hint } from "../utils/display.js";
-export async function balanceAction() {
-    requireApiKey();
-    console.log(chalk.yellow("  Balance API is not yet available."));
-    hint("Check your balance at https://aisa.one/dashboard");
+import { apiRequest } from "../api.js";
+import { formatJson, hint } from "../utils/display.js";
+export function formatMicrosUSD(micros) {
+    const value = typeof micros === "bigint" ? micros : BigInt(micros);
+    const negative = value < 0n;
+    let absolute = negative ? -value : value;
+    let cents = (absolute % 1000000n + 5000n) / 10000n;
+    let dollars = absolute / 1000000n;
+    if (cents === 100n) {
+        dollars += 1n;
+        cents = 0n;
+    }
+    return `${negative ? "-" : ""}$${dollars.toString()}.${cents.toString().padStart(2, "0")}`;
+}
+export async function balanceAction(options = {}) {
+    const key = requireApiKey();
+    const res = await apiRequest(key, "credits/balance");
+    if (!res.success || !res.data) {
+        throw new Error(res.error || "Failed to fetch balance");
+    }
+    if (options.json) {
+        console.log(formatJson(res.data));
+        return;
+    }
+    const balance = res.data;
+    console.log(`  Balance:             ${formatMicrosUSD(balance.account_balance_micros_usd)} ${balance.currency}`);
+    console.log(`  Available with key:  ${formatMicrosUSD(balance.available_balance_micros_usd)} ${balance.currency}`);
+    if (balance.api_key.unlimited) {
+        console.log("  API key limit:       Unlimited");
+    }
+    else {
+        console.log(`  API key limit:       ${formatMicrosUSD(balance.api_key.remaining_micros_usd)} remaining`);
+    }
 }
 export async function usageAction(_options) {
     requireApiKey();

package/dist/commands/chat.js

@@ -23,7 +23,7 @@ export async function chatAction(message, options) {
         error("Empty message");
         process.exit(1);
     }
-    const model = options.model || getConfig("defaultModel") || "gpt-4.1";
+    const model = options.model || getConfig("defaultModel") || "gpt-4.1-mini";
     const stream = options.stream !== false; // default true
     const messages = [];
     if (options.system) {

package/dist/commands/run.js

@@ -31,7 +31,7 @@ export async function runAction(slug, path, options) {
     }
     // Detect method
     const method = (options.method || (body ? "POST" : "GET")).toUpperCase();
-    const endpoint = `${slug}${path}`;
+    const endpoint = path.startsWith("/") ? `${slug}${path}` : `${slug}/${path}`;
     // Auto-detect domain API vs LLM API based on slug
     const domainSlugs = ["financial", "search", "youtube", "scholar", "tavily", "querit", "twitter", "services", "crypto"];
     const isDomain = domainSlugs.some((s) => slug.startsWith(s));

package/dist/commands/skills.js

@@ -2,12 +2,11 @@ import ora from "ora";
 import chalk from "chalk";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import fetch from "node-fetch";
 import { error, success, hint, truncate } from "../utils/display.js";
 import { expandHome, ensureDir, writeSkillFiles, removeDir, detectAgents } from "../utils/file.js";
 import { AGENT_DIRS } from "../constants.js";
 // --- GitHub-backed skill registry ---
-const SKILLS_REPO = "AIsa-team/OpenClaw-Skills";
+const SKILLS_REPO = "AIsa-team/agent-skills";
 const GH_API = `https://api.github.com/repos/${SKILLS_REPO}`;
 const GH_RAW = `https://raw.githubusercontent.com/${SKILLS_REPO}/main`;
 /** Fetch the repo tree and extract top-level skill folder names. */
@@ -48,7 +47,8 @@ function parseSkillFrontmatter(slug, content) {
     if (metaMatch) {
         try {
             const meta = JSON.parse(metaMatch[1]);
-            info.emoji = meta?.openclaw?.emoji || "";
+            // agent-skills repo uses metadata.aisa; legacy skills used metadata.openclaw.
+            info.emoji = meta?.aisa?.emoji || meta?.openclaw?.emoji || "";
         }
         catch {
             // ignore malformed metadata
@@ -80,8 +80,8 @@ const TEMPLATES = {
     default: `---
 name: my-skill
 description: "Describe what this skill does."
-homepage: https://openclaw.ai
-metadata: {"openclaw":{"emoji":"","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY"}}
+homepage: https://aisa.one
+metadata: {"aisa":{"emoji":"","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY","compatibility":["openclaw","claude-code","hermes"]}}
 ---
 
 # My Skill
@@ -103,8 +103,8 @@ aisa run <slug> <path> -q "param=value"
     llm: `---
 name: llm-assistant
 description: "Use AISA's unified LLM gateway to chat with 70+ AI models."
-homepage: https://openclaw.ai
-metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY"}}
+homepage: https://aisa.one
+metadata: {"aisa":{"emoji":"🤖","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY","compatibility":["openclaw","claude-code","hermes"]}}
 ---
 
 # LLM Assistant Skill
@@ -120,7 +120,7 @@ export AISA_API_KEY=sk-your-key
 ## Chat Completion
 
 \`\`\`bash
-aisa chat "Your question here" --model gpt-4.1
+aisa chat "Your question here" --model gpt-4.1-mini
 \`\`\`
 
 ## Streaming
@@ -139,8 +139,8 @@ aisa models --provider anthropic
     search: `---
 name: web-search
 description: "Search the web, YouTube, and academic papers via AISA APIs."
-homepage: https://openclaw.ai
-metadata: {"openclaw":{"emoji":"🔍","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY"}}
+homepage: https://aisa.one
+metadata: {"aisa":{"emoji":"🔍","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY","compatibility":["openclaw","claude-code","hermes"]}}
 ---
 
 # Web Search Skill
@@ -174,8 +174,8 @@ aisa scholar "transformer architecture"
     finance: `---
 name: finance-analyst
 description: "Access stock prices, earnings, SEC filings, and financial data via AISA."
-homepage: https://openclaw.ai
-metadata: {"openclaw":{"emoji":"📊","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY"}}
+homepage: https://aisa.one
+metadata: {"aisa":{"emoji":"📊","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY","compatibility":["openclaw","claude-code","hermes"]}}
 ---
 
 # Finance Analyst Skill
@@ -206,8 +206,8 @@ aisa crypto ETH --period 30d
     twitter: `---
 name: twitter-manager
 description: "Search Twitter, get user profiles and trends via AISA."
-homepage: https://openclaw.ai
-metadata: {"openclaw":{"emoji":"🐦","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY"}}
+homepage: https://aisa.one
+metadata: {"aisa":{"emoji":"🐦","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY","compatibility":["openclaw","claude-code","hermes"]}}
 ---
 
 # Twitter Manager Skill
@@ -241,8 +241,8 @@ aisa twitter trends
     video: `---
 name: video-generator
 description: "Generate videos from text prompts using AISA's video synthesis API."
-homepage: https://openclaw.ai
-metadata: {"openclaw":{"emoji":"🎬","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY"}}
+homepage: https://aisa.one
+metadata: {"aisa":{"emoji":"🎬","requires":{"bins":["curl"],"env":["AISA_API_KEY"]},"primaryEnv":"AISA_API_KEY","compatibility":["openclaw","claude-code","hermes"]}}
 ---
 
 # Video Generator Skill

package/dist/commands/twitter.js

@@ -1,6 +1,5 @@
 import ora from "ora";
 import chalk from "chalk";
-import fetch from "node-fetch";
 import { requireApiKey, getConfig, setConfig } from "../config.js";
 import { apiRequest } from "../api.js";
 import { APIS_BASE_URL } from "../constants.js";
@@ -333,9 +332,10 @@ export async function twitterUploadMediaAction(filePath, options) {
     const spinner = ora("Uploading media...").start();
     let formData;
     try {
-        const { FormData: NFFormData, fileFromSync } = await import("node-fetch");
-        formData = new NFFormData();
-        formData.append("file", fileFromSync(filePath));
+        const { readFileSync } = await import("node:fs");
+        const { basename } = await import("node:path");
+        formData = new FormData();
+        formData.append("file", new Blob([readFileSync(filePath)]), basename(filePath));
     }
     catch {
         spinner.fail("Failed to read file");

package/dist/config.js

@@ -4,7 +4,7 @@ const config = new Conf({
     projectName: "aisa-cli",
     schema: {
         apiKey: { type: "string", default: "" },
-        defaultModel: { type: "string", default: "gpt-4.1" },
+        defaultModel: { type: "string", default: "gpt-4.1-mini" },
         baseUrl: { type: "string", default: "https://api.aisa.one/v1" },
         outputFormat: { type: "string", default: "text" },
         twitterCookies: { type: "string", default: "" },

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.2";
 export declare const BASE_URL = "https://api.aisa.one";
 export declare const CLI_BASE_URL = "https://api.aisa.one/v1";
 export declare const APIS_BASE_URL = "https://api.aisa.one/apis/v1";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.2";
 export const BASE_URL = "https://api.aisa.one";
 export const CLI_BASE_URL = `${BASE_URL}/v1`;
 export const APIS_BASE_URL = `${BASE_URL}/apis/v1`;

package/dist/index.js

@@ -58,7 +58,8 @@ program
 // ── Account ──
 program
     .command("balance")
-    .description("Show credit balance (WIP)")
+    .description("Show credit balance")
+    .option("--json", "Output raw JSON")
     .action(wrap(balanceAction));
 program
     .command("usage")
@@ -107,7 +108,7 @@ program
 program
     .command("chat [message]")
     .description("Chat with AI models via the AISA gateway")
-    .option("--model <model>", "Model ID (default: gpt-4.1)")
+    .option("--model <model>", "Model ID (default: gpt-4.1-mini)")
     .option("--system <prompt>", "System prompt")
     .option("--no-stream", "Disable streaming")
     .option("--json", "Output raw JSON response")

package/dist/types.d.ts

@@ -26,8 +26,15 @@ export interface Model {
     supported_endpoint_types?: string[] | null;
 }
 export interface BalanceResponse {
-    balance: number;
     currency: string;
+    account_balance_micros_usd: number;
+    available_balance_micros_usd: number;
+    api_key: {
+        unlimited: boolean;
+        remaining_micros_usd: number;
+        used_micros_usd: number;
+    };
+    as_of: string;
 }
 export interface UsageRecord {
     timestamp: string;

package/dist/utils/streaming.d.ts

@@ -1,4 +1,3 @@
-import type { Response } from "node-fetch";
 export declare function handleSSEStream(res: Response, onToken: (token: string) => void, onDone?: (usage?: {
     prompt_tokens: number;
     completion_tokens: number;

package/dist/utils/streaming.js

@@ -2,10 +2,11 @@ export async function handleSSEStream(res, onToken, onDone) {
     const body = res.body;
     if (!body)
         throw new Error("No response body");
+    const decoder = new TextDecoder();
     let buffer = "";
     let usage;
     for await (const chunk of body) {
-        buffer += chunk.toString();
+        buffer += decoder.decode(chunk, { stream: true });
         const lines = buffer.split("\n");
         buffer = lines.pop() || "";
         for (const line of lines) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "CLI for the AISA unified AI infrastructure platform - access 70+ LLMs, web search, finance, Twitter, and video generation APIs",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,6 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "conf": "^12.0.0",
-    "node-fetch": "^3.3.2",
     "ora": "^8.0.1"
   },
   "devDependencies": {

package/tests/account.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { balanceAction, formatMicrosUSD } from "../src/commands/account.js";
+
+const balance = {
+  currency: "USD",
+  account_balance_micros_usd: 2_500_000,
+  available_balance_micros_usd: 1_000_000,
+  api_key: {
+    unlimited: false,
+    remaining_micros_usd: 1_000_000,
+    used_micros_usd: 300_000,
+  },
+  as_of: "2026-08-03T12:00:00Z",
+};
+
+describe("balanceAction", () => {
+  beforeEach(() => {
+    process.env.AISA_API_KEY = "test-balance-key";
+  });
+
+  afterEach(() => {
+    delete process.env.AISA_API_KEY;
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("formats microdollars without floating-point drift", () => {
+    expect(formatMicrosUSD(2_500_000)).toBe("$2.50");
+    expect(formatMicrosUSD(2_505_001)).toBe("$2.51");
+    expect(formatMicrosUSD(1_999_999)).toBe("$2.00");
+    expect(formatMicrosUSD(-1_500_000)).toBe("-$1.50");
+  });
+
+  it("requests the balance endpoint with the API key and renders the summary", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify(balance), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await balanceAction();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://api.aisa.one/v1/credits/balance");
+    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer test-balance-key");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("Balance:");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("$2.50 USD");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("$1.00 USD");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).not.toContain("test-balance-key");
+  });
+
+  it("renders unlimited keys", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({
+      ...balance,
+      api_key: { ...balance.api_key, unlimited: true },
+    }), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await balanceAction();
+
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("API key limit:       Unlimited");
+  });
+
+  it("supports raw JSON output", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify(balance), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await balanceAction({ json: true });
+
+    expect(JSON.parse(log.mock.calls[0][0] as string)).toEqual(balance);
+  });
+
+  it.each([401, 403, 404, 500])("raises API errors for HTTP %s", async (status) => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ error: "balance unavailable" }), { status }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(balanceAction()).rejects.toThrow(`${status}: balance unavailable`);
+  });
+
+  it("raises network errors", async () => {
+    const fetchMock = vi.fn(async () => {
+      throw new Error("connection refused");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(balanceAction()).rejects.toThrow("connection refused");
+  });
+});

package/tests/streaming.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { handleSSEStream } from "../src/utils/streaming.js";
+
+function sseResponse(chunks: string[]): Response {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const chunk of chunks) {
+        controller.enqueue(encoder.encode(chunk));
+      }
+      controller.close();
+    },
+  });
+  return new Response(stream);
+}
+
+describe("handleSSEStream", () => {
+  it("emits tokens from a native fetch Response body", async () => {
+    const res = sseResponse([
+      'data: {"choices":[{"delta":{"content":"Hello"}}]}\n\n',
+      'data: {"choices":[{"delta":{"content":" world"}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const tokens: string[] = [];
+    let done = false;
+    await handleSSEStream(
+      res,
+      (t) => tokens.push(t),
+      () => {
+        done = true;
+      }
+    );
+
+    expect(tokens.join("")).toBe("Hello world");
+    expect(done).toBe(true);
+  });
+
+  it("handles multi-byte characters split across chunks", async () => {
+    const encoder = new TextEncoder();
+    const line = encoder.encode(
+      'data: {"choices":[{"delta":{"content":"你好"}}]}\n\ndata: [DONE]\n\n'
+    );
+    // split in the middle of a multi-byte character
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(line.slice(0, 40));
+        controller.enqueue(line.slice(40));
+        controller.close();
+      },
+    });
+    const res = new Response(stream);
+
+    const tokens: string[] = [];
+    await handleSSEStream(res, (t) => tokens.push(t));
+
+    expect(tokens.join("")).toBe("你好");
+  });
+
+  it("reports usage to onDone", async () => {
+    const res = sseResponse([
+      'data: {"choices":[{"delta":{"content":"hi"}}],"usage":{"prompt_tokens":3,"completion_tokens":1}}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    let usage: { prompt_tokens: number; completion_tokens: number } | undefined;
+    await handleSSEStream(res, () => {}, (u) => {
+      usage = u;
+    });
+
+    expect(usage).toEqual({ prompt_tokens: 3, completion_tokens: 1 });
+  });
+});