@namzu/sdk 1.2.0 → 1.4.0

package/src/provider/__tests__/errors.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+	ProviderRequestError,
+	bodySaysContextOverflow,
+	classifyProviderHttpStatus,
+	isCallerAbortError,
+	isProviderRequestError,
+	parseRetryAfterMs,
+	providerVendorError,
+} from '../errors.js'
+
+describe('provider error taxonomy', () => {
+	it('classifies only context-specific limit messages as context overflow', () => {
+		expect(bodySaysContextOverflow('input token count exceeds the maximum for this model')).toBe(
+			true,
+		)
+		expect(bodySaysContextOverflow('tool count exceeds the maximum allowed')).toBe(false)
+		expect(bodySaysContextOverflow('reduce the tool list length')).toBe(false)
+	})
+
+	it('does not treat a generic HTTP 413 as model context overflow', () => {
+		expect(classifyProviderHttpStatus(413, 'request body too large at reverse proxy')).toBe(
+			'bad_request',
+		)
+		expect(classifyProviderHttpStatus(413, 'prompt is too long for requested model')).toBe(
+			'context_overflow',
+		)
+	})
+
+	it('parses both Retry-After forms and rejects stale or invalid values', () => {
+		expect(parseRetryAfterMs('2', 0)).toBe(2000)
+		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:05 GMT', 1000)).toBe(4000)
+		expect(parseRetryAfterMs('Thu, 01 Jan 1970 00:00:01 GMT', 1000)).toBeUndefined()
+		expect(parseRetryAfterMs('later', 0)).toBeUndefined()
+	})
+
+	it('drops the vendor object and its non-enumerable cause entirely', () => {
+		const secret = 'sk-FAKE-DO-NOT-LOG'
+		const vendor = new Error(`invalid api key ${secret}`, {
+			cause: new Error(`response body ${secret}`),
+		})
+		Object.assign(vendor, { status: 401 })
+
+		const classified = providerVendorError({
+			providerId: 'test-provider',
+			error: vendor,
+		})
+
+		expect(classified).toMatchObject({
+			name: 'ProviderRequestError',
+			kind: 'auth',
+			status: 401,
+			providerId: 'test-provider',
+		})
+		expect(classified.message).not.toContain(secret)
+		expect('cause' in classified).toBe(false)
+	})
+
+	it('recognizes a caller abort only when that signal actually aborted', () => {
+		const controller = new AbortController()
+		const sdkAbort = Object.assign(new Error('request aborted'), {
+			name: 'APIUserAbortError',
+		})
+
+		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(false)
+		controller.abort(new Error('user stopped'))
+		expect(isCallerAbortError(sdkAbort, controller.signal)).toBe(true)
+		expect(isCallerAbortError(controller.signal.reason, controller.signal)).toBe(true)
+	})
+
+	it('requires the complete structural contract when SDK copies differ', () => {
+		const classified = new ProviderRequestError({
+			kind: 'server',
+			providerId: 'test-provider',
+		})
+		expect(isProviderRequestError(classified)).toBe(true)
+
+		const impostor = Object.assign(new Error('not classified'), {
+			name: 'ProviderRequestError',
+			kind: 'anything',
+		})
+		expect(isProviderRequestError(impostor)).toBe(false)
+	})
+})

package/src/provider/__tests__/registry.test.ts

@@ -1,9 +1,16 @@
 import { beforeEach, describe, expect, it } from 'vitest'
-import type { LLMProvider, ProviderCapabilities } from '../../types/provider/index.js'
+import type {
+	LLMProvider,
+	LazyProviderModule,
+	ProviderCapabilities,
+} from '../../types/provider/index.js'
+import { PERMISSIVE_PROVIDER_CAPABILITIES, resolveProviderCapabilities } from '../capabilities.js'
 import { registerMock } from '../mock-register.js'
 import { MockLLMProvider } from '../mock.js'
 import {
 	DuplicateProviderError,
+	LazyProviderLoadError,
+	LazyProviderSyncCreateError,
 	ProviderRegistry,
 	UnknownProviderError,
 	__resetProviderRegistryInternal,
@@ -16,9 +23,15 @@ interface TestProviderConfig {
 	value?: string
 }
 
+interface LazyTestProviderConfig {
+	type: 'lazytest'
+	value?: string
+}
+
 declare module '../../types/provider/config.js' {
 	interface ProviderConfigRegistry {
 		test: TestProviderConfig
+		lazytest: LazyTestProviderConfig
 	}
 }
 
@@ -52,6 +65,41 @@ const TEST_CAPS: ProviderCapabilities = {
 	supportsFunctionCalling: false,
 }
 
+class LazyTestProvider implements LLMProvider {
+	readonly id = 'lazytest'
+	readonly name = 'Lazy Test'
+	constructor(
+		public readonly config: LazyTestProviderConfig,
+		readonly capabilities?: ProviderCapabilities,
+	) {}
+	async *chatStream() {
+		yield { id: 'x', delta: { content: 'ok' } }
+	}
+}
+
+const HINT_CAPS: ProviderCapabilities = {
+	supportsTools: false,
+	supportsStreaming: false,
+	supportsFunctionCalling: false,
+}
+
+const MODULE_CAPS: ProviderCapabilities = {
+	supportsTools: true,
+	supportsStreaming: true,
+	supportsFunctionCalling: true,
+	supportsVision: false,
+}
+
+function deferred<T>() {
+	let resolve!: (value: T) => void
+	let reject!: (reason?: unknown) => void
+	const promise = new Promise<T>((res, rej) => {
+		resolve = res
+		reject = rej
+	})
+	return { promise, resolve, reject }
+}
+
 describe('ProviderRegistry', () => {
 	beforeEach(() => {
 		__resetProviderRegistryInternal()
@@ -152,4 +200,221 @@ describe('ProviderRegistry', () => {
 			expect(err.name).toBe('DuplicateProviderError')
 		})
 	})
+
+	describe('registerLazy', () => {
+		it('does not invoke the loader at registration time', () => {
+			let calls = 0
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			expect(calls).toBe(0)
+			expect(ProviderRegistry.isSupported('lazytest')).toBe(true)
+			expect(ProviderRegistry.listTypes()).toContain('lazytest')
+		})
+
+		it('throws DuplicateProviderError over an existing eager registration', () => {
+			ProviderRegistry.register('test', TestProvider, TEST_CAPS)
+			expect(() =>
+				ProviderRegistry.registerLazy('test', async () => ({
+					create: (config) => new TestProvider(config),
+				})),
+			).toThrowError(DuplicateProviderError)
+		})
+
+		it('throws DuplicateProviderError over an existing lazy registration', () => {
+			const loader = async (): Promise<LazyProviderModule<LazyTestProviderConfig>> => ({
+				create: (config) => new LazyTestProvider(config),
+			})
+			ProviderRegistry.registerLazy('lazytest', loader)
+			expect(() => ProviderRegistry.registerLazy('lazytest', loader)).toThrowError(
+				DuplicateProviderError,
+			)
+		})
+
+		it('replace: true swaps between eager and lazy registrations', async () => {
+			ProviderRegistry.register('lazytest', LazyTestProvider, TEST_CAPS)
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({ create: (config) => new LazyTestProvider(config) }),
+				{ replace: true },
+			)
+			expect(() => ProviderRegistry.createProvider({ type: 'lazytest' })).toThrowError(
+				LazyProviderSyncCreateError,
+			)
+
+			ProviderRegistry.register('lazytest', LazyTestProvider, TEST_CAPS, { replace: true })
+			expect(ProviderRegistry.createProvider({ type: 'lazytest' })).toBeInstanceOf(LazyTestProvider)
+		})
+
+		it('sync create()/createProvider() always throws for lazy types, even after load', async () => {
+			ProviderRegistry.registerLazy('lazytest', async () => ({
+				create: (config) => new LazyTestProvider(config),
+			}))
+
+			expect(() => ProviderRegistry.create({ type: 'lazytest' })).toThrowError(
+				LazyProviderSyncCreateError,
+			)
+
+			await ProviderRegistry.createAsync({ type: 'lazytest' })
+			expect(() => ProviderRegistry.createProvider({ type: 'lazytest' })).toThrowError(
+				LazyProviderSyncCreateError,
+			)
+		})
+
+		it('unregister removes a lazy registration', () => {
+			ProviderRegistry.registerLazy('lazytest', async () => ({
+				create: (config) => new LazyTestProvider(config),
+			}))
+			expect(ProviderRegistry.unregister('lazytest')).toBe(true)
+			expect(ProviderRegistry.isSupported('lazytest')).toBe(false)
+		})
+	})
+
+	describe('createAsync', () => {
+		it('first create invokes the loader once; subsequent creates reuse the cached factory', async () => {
+			let calls = 0
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			const first = await ProviderRegistry.createAsync({ type: 'lazytest', value: 'a' })
+			const second = await ProviderRegistry.createAsync({ type: 'lazytest', value: 'b' })
+
+			expect(calls).toBe(1)
+			expect(first.provider).toBeInstanceOf(LazyTestProvider)
+			expect(second.provider).toBeInstanceOf(LazyTestProvider)
+			expect((second.provider as LazyTestProvider).config.value).toBe('b')
+		})
+
+		it('concurrent first-creates share a single loader invocation', async () => {
+			let calls = 0
+			const gate = deferred<void>()
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				await gate.promise
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			const a = ProviderRegistry.createAsync({ type: 'lazytest' })
+			const b = ProviderRegistry.createAsync({ type: 'lazytest' })
+			gate.resolve()
+
+			const [ra, rb] = await Promise.all([a, b])
+			expect(calls).toBe(1)
+			expect(ra.provider).toBeInstanceOf(LazyTestProvider)
+			expect(rb.provider).toBeInstanceOf(LazyTestProvider)
+		})
+
+		it('loader rejection surfaces as LazyProviderLoadError and the next create retries', async () => {
+			let calls = 0
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				if (calls === 1) {
+					throw new Error('transient network failure')
+				}
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			const failure = await ProviderRegistry.createAsync({ type: 'lazytest' }).catch(
+				(err: unknown) => err,
+			)
+			expect(failure).toBeInstanceOf(LazyProviderLoadError)
+			expect((failure as LazyProviderLoadError).providerType).toBe('lazytest')
+			expect(((failure as LazyProviderLoadError).cause as Error).message).toBe(
+				'transient network failure',
+			)
+
+			const { provider } = await ProviderRegistry.createAsync({ type: 'lazytest' })
+			expect(calls).toBe(2)
+			expect(provider).toBeInstanceOf(LazyTestProvider)
+		})
+
+		it('rejects with LazyProviderLoadError when the loader resolves an invalid module shape', async () => {
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({}) as unknown as LazyProviderModule<LazyTestProviderConfig>,
+			)
+			await expect(ProviderRegistry.createAsync({ type: 'lazytest' })).rejects.toThrowError(
+				LazyProviderLoadError,
+			)
+		})
+
+		it('works for eagerly registered types too', async () => {
+			const { provider, capabilities } = await ProviderRegistry.createAsync({
+				type: 'mock',
+				model: 'test-model',
+			})
+			expect(provider).toBeInstanceOf(MockLLMProvider)
+			expect(capabilities.supportsStreaming).toBe(true)
+		})
+
+		it('rejects with UnknownProviderError for unregistered types', async () => {
+			await expect(
+				ProviderRegistry.createAsync({ type: 'nonexistent' } as unknown as { type: 'mock' }),
+			).rejects.toThrowError(UnknownProviderError)
+		})
+	})
+
+	describe('lazy capabilities', () => {
+		it('answers with the registration hint before load, without invoking the loader', () => {
+			let calls = 0
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => {
+					calls++
+					return { create: (config) => new LazyTestProvider(config) }
+				},
+				{ capabilities: HINT_CAPS },
+			)
+
+			expect(ProviderRegistry.getCapabilities('lazytest')).toEqual(HINT_CAPS)
+			expect(calls).toBe(0)
+		})
+
+		it('answers permissively before load when no hint was given', () => {
+			ProviderRegistry.registerLazy('lazytest', async () => ({
+				create: (config) => new LazyTestProvider(config),
+			}))
+			expect(ProviderRegistry.getCapabilities('lazytest')).toEqual(PERMISSIVE_PROVIDER_CAPABILITIES)
+		})
+
+		it('module capabilities replace the hint after load', async () => {
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({
+					create: (config) => new LazyTestProvider(config),
+					capabilities: MODULE_CAPS,
+				}),
+				{ capabilities: HINT_CAPS },
+			)
+
+			const { capabilities } = await ProviderRegistry.createAsync({ type: 'lazytest' })
+			expect(capabilities).toEqual(MODULE_CAPS)
+			expect(ProviderRegistry.getCapabilities('lazytest')).toEqual(MODULE_CAPS)
+		})
+
+		it('the constructed instance own capabilities win at run time over any hint', async () => {
+			const instanceCaps: ProviderCapabilities = {
+				supportsTools: true,
+				supportsStreaming: true,
+				supportsFunctionCalling: false,
+				supportsVision: false,
+			}
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({ create: (config) => new LazyTestProvider(config, instanceCaps) }),
+				{ capabilities: HINT_CAPS },
+			)
+
+			const { provider } = await ProviderRegistry.createAsync({ type: 'lazytest' })
+			// The query runtime negotiates against the instance, not the registry:
+			const resolved = resolveProviderCapabilities(provider)
+			expect(resolved.supportsTools).toBe(true)
+			expect(resolved.supportsFunctionCalling).toBe(false)
+			expect(resolved.supportsVision).toBe(false)
+		})
+	})
 })