| export interface KeyCommandOptions { |
| url: string; |
| args: string[]; |
| token?: string; |
| key?: string; |
| keyId?: number; |
| timeoutMs?: number; |
| dryRun: boolean; |
| } |
|
|
| interface KeyRow { |
| id: number; |
| platform: string; |
| enabled: boolean; |
| status: string; |
| lastHealthError?: string | null; |
| modelScope?: string[] | null; |
| models?: Array<{ id: number; kind: string }>; |
| } |
|
|
| interface ModelRow { |
| id: number; |
| platform: string; |
| modelId: string; |
| enabled: boolean; |
| keyId?: number | null; |
| } |
|
|
| export function keysHelp(): string { |
| return [ |
| 'Provider key management (dashboard authentication):', |
| ' freellmapi keys add <platform> [--key KEY]', |
| ' freellmapi keys list', |
| ' freellmapi keys remove <platform> [--id ID]', |
| ' freellmapi keys test <platform> [--id ID]', |
| '', |
| 'Options: --url URL, --token TOKEN, --timeout MS (default 30000)', |
| 'Use FREELLMAPI_DASHBOARD_TOKEN or --token for the dashboard session token.', |
| 'The unified --api-key / FREELLMAPI_API_KEY is not dashboard authentication.', |
| 'Omit --key for hidden terminal input. Keyless providers do not prompt.', |
| 'remove requires --id when a platform has multiple keys; test checks all matches.', |
| 'list shows enabled chat model counts, respecting each key\'s model scope.', |
| 'add saves the key, then checks it; failed validation leaves it saved and exits 1.', |
| ].join('\n'); |
| } |
|
|
| function gatewayRoot(value: string): string { |
| let url: URL; |
| try { url = new URL(value.trim()); } catch { throw new Error('--url must be an HTTP(S) gateway URL'); } |
| if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) { |
| throw new Error('--url must be an HTTP(S) URL without credentials, a query, or a fragment'); |
| } |
| return url.href.replace(/\/+$/, '').replace(/\/v1$/i, ''); |
| } |
|
|
| function modelCount(key: KeyRow, models: ModelRow[]): number { |
| const customIds = new Set(key.models?.filter(m => m.kind === 'chat').map(m => m.id)); |
| return models.filter(model => model.enabled && model.platform === key.platform |
| && (!key.modelScope?.length || key.modelScope.includes(model.modelId)) |
| && (key.platform === 'custom' ? customIds.has(model.id) : !model.keyId || model.keyId === key.id)).length; |
| } |
|
|
| const statuses = new Set(['healthy', 'invalid', 'unknown', 'rate_limited', 'error']); |
| function statusOf(status: string): string { |
| return statuses.has(status) ? status : 'unknown'; |
| } |
|
|
| export async function runKeys( |
| options: KeyCommandOptions, |
| prompt: () => Promise<string>, |
| ): Promise<number> { |
| const [action, rawPlatform, ...extra] = options.args; |
| if (!action || !['add', 'list', 'remove', 'test'].includes(action)) { |
| throw new Error(`Expected keys add, list, remove, or test.\n\n${keysHelp()}`); |
| } |
| if (extra.length || (action === 'list' ? rawPlatform !== undefined : !rawPlatform)) { |
| throw new Error(`Invalid arguments for keys ${action}.\n\n${keysHelp()}`); |
| } |
| if (options.dryRun) throw new Error('--dry-run is not supported by keys; no request was made'); |
| if (options.key !== undefined && action !== 'add') throw new Error('--key is only supported by keys add'); |
| if (options.keyId !== undefined && action !== 'remove' && action !== 'test') { |
| throw new Error('--id is only supported by keys remove and keys test'); |
| } |
| const platform = rawPlatform?.toLowerCase(); |
| if (platform && !/^[a-z][a-z0-9_-]*$/.test(platform)) throw new Error('Invalid provider platform identifier'); |
| const token = options.token?.trim(); |
| if (!token) throw new Error('Set FREELLMAPI_DASHBOARD_TOKEN or pass --token with a dashboard session token'); |
| const root = gatewayRoot(options.url); |
| const timeout = options.timeoutMs ?? 30_000; |
| if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 2_147_483_647) { |
| throw new Error('--timeout must be a positive integer of at most 2147483647 milliseconds'); |
| } |
|
|
| async function request<T>(path: string, method = 'GET', body?: unknown): Promise<T> { |
| let response: Response; |
| try { |
| response = await fetch(`${root}${path}`, { |
| method, |
| headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) }, |
| body: body === undefined ? undefined : JSON.stringify(body), |
| signal: AbortSignal.timeout(timeout), |
| redirect: 'error', |
| cache: 'no-store', |
| }); |
| } catch { |
| throw new Error('Could not complete the dashboard request. Check --url, connectivity, and --timeout.'); |
| } |
| |
| |
| if (response.status === 401 || response.status === 403) { |
| throw new Error('Dashboard authentication failed. Supply a current dashboard session token with --token or FREELLMAPI_DASHBOARD_TOKEN.'); |
| } |
| if (!response.ok) throw new Error(`Dashboard request failed (HTTP ${response.status})`); |
| if (response.status === 204) return undefined as T; |
| try { return await response.json() as T; } catch { throw new Error('The gateway returned an invalid JSON response'); } |
| } |
|
|
| async function listKeys(): Promise<KeyRow[]> { |
| const rows = await request<KeyRow[]>('/api/keys'); |
| if (!Array.isArray(rows) || rows.some(row => !row || !Number.isSafeInteger(row.id) |
| || row.id <= 0 || typeof row.platform !== 'string')) { |
| throw new Error('The gateway returned an invalid key list'); |
| } |
| return rows; |
| } |
|
|
| async function check(id: number, provider: string): Promise<number> { |
| const result = await request<{ keyId: number; status: string }>(`/api/health/check/${id}`, 'POST'); |
| if (!result || result.keyId !== id) throw new Error('The gateway returned an invalid health check result'); |
| |
| |
| const current = (await listKeys()).find(row => row.id === id); |
| if (!current) throw new Error('The key no longer exists'); |
| const status = statusOf(result.status === 'healthy' ? current.status : result.status); |
| const inconclusive = !!current.lastHealthError && status !== 'invalid'; |
| process.stdout.write(`${id}\t${provider}\t${inconclusive ? `inconclusive (stored status: ${statusOf(current.status)})` : status}\n`); |
| return status === 'healthy' && !inconclusive ? 0 : 1; |
| } |
|
|
| if (action === 'add') { |
| const { providers } = await request<{ providers: Array<{ platform: string; keyless?: boolean }> }>('/api/keys/providers'); |
| const provider = providers.find(p => p.platform === platform); |
| if (!provider) { |
| throw new Error(platform === 'custom' |
| ? 'Custom endpoints require URL and model registration; add them in the dashboard.' |
| : 'Unknown provider platform. Use the provider identifier shown in the dashboard.'); |
| } |
| const value = (options.key ?? (provider.keyless ? '' : await prompt())).trim(); |
| if (!value && !provider.keyless) throw new Error('A provider API key is required'); |
| const saved = await request<{ id: number }>('/api/keys', 'POST', { platform, key: value }); |
| if (!Number.isSafeInteger(saved.id) || saved.id <= 0) throw new Error('The gateway did not return a valid saved key ID'); |
| process.stdout.write(`Saved ${platform} key ${saved.id}. Checking it now; the key remains saved if validation fails.\n`); |
| return check(saved.id, platform!); |
| } |
|
|
| const rows = await listKeys(); |
| if (action === 'list') { |
| if (!rows.length) { |
| process.stdout.write('No provider keys configured.\n'); |
| return 0; |
| } |
| const models = await request<ModelRow[]>('/api/models'); |
| if (!Array.isArray(models)) throw new Error('The gateway returned an invalid model list'); |
| process.stdout.write('ID\tPLATFORM\tMODELS\tENABLED\tSTATUS\n'); |
| for (const row of rows) { |
| const provider = /^[a-z][a-z0-9_-]*$/.test(row.platform) ? row.platform : 'unknown'; |
| process.stdout.write(`${row.id}\t${provider}\t${modelCount(row, models)}\t${row.enabled ? 'enabled' : 'disabled'}\t${statusOf(row.status)}\n`); |
| } |
| return 0; |
| } |
|
|
| const selected = rows.filter(row => row.platform === platform && (options.keyId === undefined || row.id === options.keyId)); |
| if (!selected.length) throw new Error('No matching key found for that platform and ID'); |
| if (action === 'remove') { |
| if (selected.length > 1) throw new Error('Multiple keys match. Run keys list and specify one with --id.'); |
| await request(`/api/keys/${selected[0].id}`, 'DELETE'); |
| process.stdout.write(`Removed ${platform} key ${selected[0].id}.\n`); |
| return 0; |
| } |
|
|
| let exitCode = 0; |
| for (const row of selected) exitCode = Math.max(exitCode, await check(row.id, platform!)); |
| return exitCode; |
| } |
|
|
