@ -1,10 +1,11 @@
import { describe , expect , it } from "vitest" ; import { describe , expect , it } from "vitest" ;
import { createXllm , type XStreamEvent } from "./index" ; import { createXllm , XllmError , registerAdapter , type XStreamEvent } from "./index" ;
import type { ProviderAdapter } from "./providers/types" ;
const toJsonResponse = ( payload : unknown ) : Response = > const toJsonResponse = ( payload : unknown , status = 200 , headers? : Record < string , string > ) : Response = >
new Response ( JSON . stringify ( payload ) , { new Response ( JSON . stringify ( payload ) , {
status : 200 , status ,
headers : { "content-type" : "application/json" } , headers : { "content-type" : "application/json" , . . . headers } ,
} ) ; } ) ;
const toSSEBody = ( frames : string [ ] ) : ReadableStream < Uint8Array > = > { const toSSEBody = ( frames : string [ ] ) : ReadableStream < Uint8Array > = > {
@ -53,6 +54,19 @@ describe("xllm", () => {
expect ( result . usage ? . totalTokens ) . toBe ( 2 ) ; expect ( result . usage ? . totalTokens ) . toBe ( 2 ) ;
} ) ; } ) ;
it ( "accepts string content in messages" , async ( ) = > {
const mockFetch : typeof fetch = async ( ) = >
toJsonResponse ( {
model : "gpt-4o-mini" ,
choices : [ { message : { content : "hi back" } , finish_reason : "stop" } ] ,
} ) ;
const client = createXllm ( { provider : "openai-compatible" , apiKey : "test" , fetch : mockFetch } ) ;
const result = await client . generate ( {
messages : [ { role : "user" , content : "hello" } ] ,
} ) ;
expect ( result . text ) . toBe ( "hi back" ) ;
} ) ;
it ( "streams text delta events" , async ( ) = > { it ( "streams text delta events" , async ( ) = > {
const sseFrames = [ const sseFrames = [
'data: {"id":"r1","model":"deepseek-chat","choices":[{"delta":{"content":"he"},"finish_reason":null}]}\n\n' , 'data: {"id":"r1","model":"deepseek-chat","choices":[{"delta":{"content":"he"},"finish_reason":null}]}\n\n' ,
@ -260,7 +274,7 @@ describe("xllm", () => {
expect ( result . response . text ) . toContain ( "工具错误" ) ; expect ( result . response . text ) . toContain ( "工具错误" ) ;
} ) ; } ) ;
it ( "sends thinking and reasoning_effort for DeepSeek-style bodies" , async ( ) = > { it ( "sends thinking and reasoning_effort via providerExtras for DeepSeek-style bodies" , async ( ) = > {
const bodies : Array < Record < string , unknown > > = [ ] ; const bodies : Array < Record < string , unknown > > = [ ] ;
const mockFetch : typeof fetch = async ( _input , init ) = > { const mockFetch : typeof fetch = async ( _input , init ) = > {
bodies . push ( typeof init ? . body === "string" ? JSON . parse ( init . body ) : { } ) ; bodies . push ( typeof init ? . body === "string" ? JSON . parse ( init . body ) : { } ) ;
@ -272,14 +286,13 @@ describe("xllm", () => {
const client = createXllm ( { provider : "deepseek" , apiKey : "test" , fetch : mockFetch } ) ; const client = createXllm ( { provider : "deepseek" , apiKey : "test" , fetch : mockFetch } ) ;
await client . generate ( { await client . generate ( {
messages : [ { role : "user" , content : [ { type : "text" , text : "hi" } ] } ] , messages : [ { role : "user" , content : [ { type : "text" , text : "hi" } ] } ] ,
thinking : { type : "disabled" } , providerExtras : { thinking : { type : "disabled" } , reasoning_effort : "high" } ,
reasoningEffort : "medium" ,
} ) ; } ) ;
expect ( bodies [ 0 ] ? . thinking ) . toEqual ( { type : "disabled" } ) ; expect ( bodies [ 0 ] ? . thinking ) . toEqual ( { type : "disabled" } ) ;
expect ( bodies [ 0 ] ? . reasoning_effort ) . toBe ( "high" ) ; expect ( bodies [ 0 ] ? . reasoning_effort ) . toBe ( "high" ) ;
await client . generate ( { await client . generate ( {
messages : [ { role : "user" , content : [ { type : "text" , text : "hi" } ] } ] , messages : [ { role : "user" , content : [ { type : "text" , text : "hi" } ] } ] ,
reasoningE ffort: "xhigh " , providerExtras : { reasoning_e ffort: "ma x" } ,
} ) ; } ) ;
expect ( bodies [ 1 ] ? . reasoning_effort ) . toBe ( "max" ) ; expect ( bodies [ 1 ] ? . reasoning_effort ) . toBe ( "max" ) ;
} ) ; } ) ;
@ -349,4 +362,241 @@ describe("xllm", () => {
expect ( body . temperature ) . toBe ( 0.9 ) ; expect ( body . temperature ) . toBe ( 0.9 ) ;
expect ( body . custom_vendor_flag ) . toBe ( true ) ; expect ( body . custom_vendor_flag ) . toBe ( true ) ;
} ) ; } ) ;
it ( "does not include undefined optional fields in request body" , async ( ) = > {
let body : Record < string , unknown > = { } ;
const mockFetch : typeof fetch = async ( _input , init ) = > {
body = typeof init ? . body === "string" ? JSON . parse ( init . body ) : { } ;
return toJsonResponse ( {
choices : [ { message : { content : "ok" } , finish_reason : "stop" } ] ,
} ) ;
} ;
const client = createXllm ( { provider : "openai-compatible" , apiKey : "test" , fetch : mockFetch } ) ;
await client . generate ( {
messages : [ { role : "user" , content : "hi" } ] ,
} ) ;
expect ( body ) . not . toHaveProperty ( "temperature" ) ;
expect ( body ) . not . toHaveProperty ( "top_p" ) ;
expect ( body ) . not . toHaveProperty ( "max_tokens" ) ;
expect ( body ) . not . toHaveProperty ( "metadata" ) ;
} ) ;
// --- 错误路径测试 ---
it ( "throws AUTH_ERROR on 401 response" , async ( ) = > {
const mockFetch : typeof fetch = async ( ) = >
toJsonResponse ( { error : { message : "Invalid API key" } } , 401 , { "x-request-id" : "req_123" } ) ;
const client = createXllm ( { provider : "openai-compatible" , apiKey : "bad" , fetch : mockFetch } ) ;
try {
await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( error ) . toBeInstanceOf ( XllmError ) ;
expect ( ( error as XllmError ) . code ) . toBe ( "AUTH_ERROR" ) ;
expect ( ( error as XllmError ) . statusCode ) . toBe ( 401 ) ;
expect ( ( error as XllmError ) . responseHeaders ? . [ "x-request-id" ] ) . toBe ( "req_123" ) ;
}
} ) ;
it ( "throws RATE_LIMIT on 429 response" , async ( ) = > {
const mockFetch : typeof fetch = async ( ) = >
toJsonResponse ( { error : { message : "Rate limit exceeded" } } , 429 ) ;
const client = createXllm ( { provider : "deepseek" , apiKey : "test" , fetch : mockFetch } ) ;
try {
await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( error ) . toBeInstanceOf ( XllmError ) ;
expect ( ( error as XllmError ) . code ) . toBe ( "RATE_LIMIT" ) ;
}
} ) ;
it ( "throws NETWORK_ERROR when fetch throws" , async ( ) = > {
const mockFetch : typeof fetch = async ( ) = > {
throw new TypeError ( "fetch failed" ) ;
} ;
const client = createXllm ( { provider : "openai-compatible" , apiKey : "test" , fetch : mockFetch } ) ;
try {
await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( error ) . toBeInstanceOf ( XllmError ) ;
expect ( ( error as XllmError ) . code ) . toBe ( "NETWORK_ERROR" ) ;
}
} ) ;
it ( "throws AUTH_ERROR when apiKey is missing" , async ( ) = > {
const client = createXllm ( { provider : "openai-compatible" } ) ;
try {
await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( error ) . toBeInstanceOf ( XllmError ) ;
expect ( ( error as XllmError ) . code ) . toBe ( "AUTH_ERROR" ) ;
}
} ) ;
it ( "throws when maxRounds is exceeded in chatWithTools" , async ( ) = > {
const mockFetch : typeof fetch = async ( ) = >
toJsonResponse ( {
choices : [
{
message : {
content : "" ,
tool_calls : [ { id : "c1" , function : { name : "loop_tool" , arguments : "{}" } } ] ,
} ,
finish_reason : "tool_calls" ,
} ,
] ,
} ) ;
const client = createXllm ( { provider : "deepseek" , apiKey : "test" , fetch : mockFetch } ) ;
try {
await client . chatWithTools (
{ messages : [ { role : "user" , content : "hi" } ] , tools : [ { name : "loop_tool" } ] , maxRounds : 1 } ,
{ loop_tool : ( ) = > "ok" } ,
) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( error ) . toBeInstanceOf ( XllmError ) ;
expect ( ( error as XllmError ) . code ) . toBe ( "PROVIDER_ERROR" ) ;
expect ( ( error as XllmError ) . message ) . toContain ( "maxRounds" ) ;
}
} ) ;
it ( "throws INVALID_REQUEST when maxRounds < 1" , async ( ) = > {
const client = createXllm ( { provider : "deepseek" , apiKey : "test" , fetch : async ( ) = > new Response ( ) } ) ;
try {
await client . chatWithTools (
{ messages : [ { role : "user" , content : "hi" } ] , tools : [ ] , maxRounds : 0 } ,
{ } ,
) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( error ) . toBeInstanceOf ( XllmError ) ;
expect ( ( error as XllmError ) . code ) . toBe ( "INVALID_REQUEST" ) ;
}
} ) ;
it ( "skips tool call when strategy is skip and no executor found" , async ( ) = > {
let call = 0 ;
const mockFetch : typeof fetch = async ( ) = > {
call += 1 ;
if ( call === 1 ) {
return toJsonResponse ( {
choices : [
{
message : {
content : "" ,
tool_calls : [ { id : "c1" , function : { name : "unknown_tool" , arguments : "{}" } } ] ,
} ,
finish_reason : "tool_calls" ,
} ,
] ,
} ) ;
}
return toJsonResponse ( {
choices : [ { message : { content : "done" } , finish_reason : "stop" } ] ,
} ) ;
} ;
const client = createXllm ( { provider : "deepseek" , apiKey : "test" , fetch : mockFetch } ) ;
const result = await client . chatWithTools (
{
messages : [ { role : "user" , content : "hi" } ] ,
tools : [ { name : "unknown_tool" } ] ,
toolErrorStrategy : "skip" ,
} ,
{ } ,
) ;
expect ( result . toolCallsExecuted ) . toBe ( 0 ) ;
expect ( result . response . text ) . toBe ( "done" ) ;
} ) ;
it ( "throws for unknown provider" , async ( ) = > {
const client = createXllm ( { provider : "unknown-provider" as any , apiKey : "test" } ) ;
try {
await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect . unreachable ( "Should have thrown" ) ;
} catch ( error ) {
expect ( ( error as Error ) . message ) . toContain ( "No adapter registered" ) ;
}
} ) ;
it ( "registerAdapter allows adding custom provider" , async ( ) = > {
const customAdapter : ProviderAdapter = {
name : "custom-test" ,
toProviderRequest : ( ) = > ( {
method : "POST" ,
url : "https://custom.example.com/v1/chat/completions" ,
headers : { "content-type" : "application/json" , authorization : "Bearer test" } ,
body : { model : "custom-model" , messages : [ ] , stream : false } ,
} ) ,
fromProviderResponse : ( ) = > ( {
text : "custom response" ,
toolCalls : [ ] ,
provider : "custom-test" ,
model : "custom-model" ,
} ) ,
fromProviderStreamChunk : ( ) = > [ ] ,
normalizeError : ( err : any ) = >
new XllmError ( { code : "PROVIDER_ERROR" , message : err?.message ? ? "error" , provider : "custom-test" } ) ,
} ;
registerAdapter ( customAdapter ) ;
const mockFetch : typeof fetch = async ( ) = >
toJsonResponse ( {
choices : [ { message : { content : "custom response" } , finish_reason : "stop" } ] ,
} ) ;
const client = createXllm ( { provider : "custom-test" , apiKey : "test" , fetch : mockFetch } ) ;
const result = await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect ( result . text ) . toBe ( "custom response" ) ;
expect ( result . provider ) . toBe ( "custom-test" ) ;
} ) ;
it ( "with() creates derived client with overrides" , async ( ) = > {
const mockFetch : typeof fetch = async ( ) = >
toJsonResponse ( {
choices : [ { message : { content : "derived" } , finish_reason : "stop" } ] ,
} ) ;
const base = createXllm ( { provider : "openai-compatible" , apiKey : "test" , fetch : mockFetch } ) ;
const derived = base . with ( { model : "gpt-4o" } ) ;
const result = await derived . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect ( result . text ) . toBe ( "derived" ) ;
} ) ;
it ( "onBeforeRequest hook modifies request" , async ( ) = > {
let capturedHeaders : Record < string , string > = { } ;
const mockFetch : typeof fetch = async ( _input , init ) = > {
capturedHeaders = Object . fromEntries ( new Headers ( ( init as RequestInit ) ? . headers as Headers ) ) ;
return toJsonResponse ( {
choices : [ { message : { content : "ok" } , finish_reason : "stop" } ] ,
} ) ;
} ;
const customAdapter : ProviderAdapter = {
name : "hook-test" ,
toProviderRequest : ( ) = > ( {
method : "POST" ,
url : "https://hook.example.com/v1/chat/completions" ,
headers : { "content-type" : "application/json" , authorization : "Bearer test" } ,
body : { model : "hook-model" , messages : [ ] , stream : false } ,
} ) ,
fromProviderResponse : ( ) = > ( {
text : "ok" ,
toolCalls : [ ] ,
provider : "hook-test" ,
model : "hook-model" ,
} ) ,
fromProviderStreamChunk : ( ) = > [ ] ,
normalizeError : ( err : any ) = >
new XllmError ( { code : "PROVIDER_ERROR" , message : err?.message ? ? "error" , provider : "hook-test" } ) ,
onBeforeRequest ( request ) {
return { . . . request , headers : { . . . request . headers , "x-custom-signature" : "signed" } } ;
} ,
} ;
registerAdapter ( customAdapter ) ;
const client = createXllm ( { provider : "hook-test" , apiKey : "test" , fetch : mockFetch } ) ;
await client . generate ( { messages : [ { role : "user" , content : "hi" } ] } ) ;
expect ( capturedHeaders [ "x-custom-signature" ] ) . toBe ( "signed" ) ;
} ) ;
} ) ; } ) ;
