@cameronpak/zo-computer

export { ZO_API_KEY_SECRET, ZO_BASE_URL } from './core'
export {
	ZoApiError,
	ZoConfigError,
	ZoNetworkError,
	ZoParseError,
	ZoStreamError,
	type ZoError,
	type ZoRequestError,
} from './errors'
export type {
	ZoAskInput,
	ZoAskResult,
	ZoClientOptions,
	ZoModel,
	ZoPersona,
	ZoRetryOptions,
	ZoStream,
	ZoStreamEvent,
} from './types'

/**
 * Package overview for the Zo Computer client.
 *
 * Import the endpoint exports directly. This default export exists so agents
 * can read the surface in one call.
 *
 * @example
 * import overview from 'kody:@cameronpak/zo-computer'
 * const surface = await overview()
 */
export default async function zoComputerOverview() {
	return {
		baseUrl: 'https://api.zo.computer',
		secret: 'ZO_API_KEY',
		exports: [
			{
				name: './ask',
				summary: 'Send one message to Zo and wait for the whole answer.',
				specifier: 'kody:@cameronpak/zo-computer/ask',
			},
			{
				name: './ask-stream',
				summary:
					'Send one message and read the answer as Server-Sent Events. Import only.',
				specifier: 'kody:@cameronpak/zo-computer/ask-stream',
			},
			{
				name: './list-models',
				summary: 'List models you can pass as modelName.',
				specifier: 'kody:@cameronpak/zo-computer/list-models',
			},
			{
				name: './list-personas',
				summary: 'List personas you can pass as personaId.',
				specifier: 'kody:@cameronpak/zo-computer/list-personas',
			},
			{
				name: './call',
				summary:
					'Run ask, listModels, or listPersonas and return plain JSON. Use this from packages.invoke.',
				specifier: 'kody:@cameronpak/zo-computer/call',
			},
		],
		errorTags: [
			'ZoConfigError',
			'ZoNetworkError',
			'ZoApiError',
			'ZoParseError',
			'ZoStreamError',
		],
		notes: [
			'Every export returns a better-result Result. Failures are values, not exceptions.',
			'Read result.status: "ok" carries value, "error" carries error.',
			'Each error carries a _tag, so error.match({ ... }) is exhaustive.',
			'Omit apiKey to use the ZO_API_KEY Kody secret. Pass apiKey to override it.',
			'A Result cannot cross packages.invoke. Import the direct exports, or invoke ./call.',
			'/models/available answers without a valid key, so it is not an auth test.',
		],
	}
}