@eightstate/escli 0.5.0

package/dist/services/audio.js

@@ -0,0 +1,454 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../lib/escli-error.js';
+import { callWithRetry, vendKeyForService } from './credentials.js';
+const ASSEMBLYAI_BASE_URL = 'https://api.assemblyai.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_UPLOAD_TIMEOUT_MS = 300_000;
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const MAX_POLL_ATTEMPTS = 1_200;
+export async function transcribeAudio(options) {
+    const started = Date.now();
+    const { audioUrl, credential } = isRemoteUrl(options.source)
+        ? { audioUrl: options.source, credential: await resolveAssemblyAiCredential() }
+        : await uploadLocalAudio(options.source);
+    const request = await requestJson({
+        method: 'POST',
+        path: '/v2/transcript',
+        apiKey: credential.apiKey,
+        baseUrl: credential.baseUrl,
+        jsonBody: buildTranscriptBody(options, audioUrl),
+    });
+    const transcriptId = stringValue(request.id);
+    if (!transcriptId)
+        throw new EscliError('invalid AssemblyAI transcript response: missing id', { code: ErrorCode.GateInvalidResponse, details: request });
+    await rememberTranscriptCredential(transcriptId, credential);
+    const transcript = await pollTranscript(transcriptId, credential);
+    if (transcript.status === 'error') {
+        throw new EscliError(stringValue(transcript.error) ?? 'transcription failed', {
+            code: ErrorCode.AudioTranscriptionFailed,
+            details: { id: transcriptId, error: transcript.error },
+        });
+    }
+    if (options.format === 'text' && !options.output)
+        return summarizeTranscript(transcript, roundElapsed((Date.now() - started) / 1000));
+    const output = await formatTranscript(transcript, options.format, credential);
+    if (options.output) {
+        await writeOutputFile(options.output, output);
+        return { path: options.output, format: options.format, id: transcriptId };
+    }
+    if (options.format === 'json')
+        return transcript;
+    return { output, format: options.format, id: transcriptId };
+}
+export async function getAudioStatus(transcriptId) {
+    const { transcript } = await fetchTranscriptWithCredential(transcriptId);
+    return { id: transcriptId, status: stringValue(transcript.status) ?? 'unknown', error: transcript.error ?? null };
+}
+export async function getAudioTranscript(transcriptId, format, outputPath) {
+    const { transcript, credential } = await fetchTranscriptWithCredential(transcriptId);
+    if (transcript.status !== 'completed') {
+        throw new EscliError(stringValue(transcript.error) ?? `transcript not ready: ${stringValue(transcript.status) ?? 'unknown'}`, {
+            code: transcript.status === 'error' ? ErrorCode.AudioTranscriptionFailed : ErrorCode.AudioTranscriptNotFound,
+            details: { id: transcriptId, status: transcript.status, error: transcript.error },
+        });
+    }
+    const output = await formatTranscript(transcript, format, credential);
+    if (outputPath) {
+        await writeOutputFile(outputPath, output);
+        return { path: outputPath, format };
+    }
+    if (format === 'json')
+        return transcript;
+    return { output, format };
+}
+export async function listAudioTranscripts() {
+    const credential = await resolveAssemblyAiCredential();
+    const data = await requestJson({ method: 'GET', path: '/v2/transcript?limit=20', apiKey: credential.apiKey, baseUrl: credential.baseUrl });
+    const transcripts = arrayValue(data.transcripts)
+        .map((item) => recordValue(item))
+        .filter((item) => Boolean(item))
+        .map((item) => ({ ...item, id: String(item.id ?? '') }));
+    return { transcripts, count: transcripts.length };
+}
+export async function formatTranscript(transcript, format, credential) {
+    if (format === 'json')
+        return JSON.stringify(transcript, null, 2);
+    if (format === 'srt' || format === 'vtt') {
+        const id = stringValue(transcript.id);
+        if (!id)
+            throw new EscliError('invalid AssemblyAI transcript response: missing id', { code: ErrorCode.GateInvalidResponse, details: transcript });
+        const resolved = credential ?? await resolveAssemblyAiCredential();
+        return requestText({ method: 'GET', path: `/v2/transcript/${encodeURIComponent(id)}/${format}`, apiKey: resolved.apiKey, baseUrl: resolved.baseUrl, expectText: true });
+    }
+    return formatTranscriptText(transcript);
+}
+export function formatTranscriptText(data) {
+    const lines = [];
+    const utterances = Array.isArray(data.utterances) ? data.utterances : [];
+    if (utterances.length > 0) {
+        for (const utterance of utterances) {
+            const speaker = stringValue(utterance.speaker) ?? '?';
+            const text = stringValue(utterance.text) ?? '';
+            lines.push(`Speaker ${speaker}: ${text}`);
+        }
+    }
+    else if (stringValue(data.text)) {
+        lines.push(stringValue(data.text) ?? '');
+    }
+    const chapters = arrayValue(data.chapters).map(recordValue).filter((item) => Boolean(item));
+    if (chapters.length > 0) {
+        lines.push('\n--- Chapters ---');
+        for (const chapter of chapters) {
+            lines.push(`\n## ${stringValue(chapter.headline) ?? ''}`);
+            lines.push(stringValue(chapter.summary) ?? '');
+        }
+    }
+    if (stringValue(data.summary))
+        lines.push(`\n--- Summary ---\n${stringValue(data.summary) ?? ''}`);
+    const sentiments = arrayValue(data.sentiment_analysis_results).map(recordValue).filter((item) => Boolean(item));
+    if (sentiments.length > 0) {
+        lines.push('\n--- Sentiment ---');
+        for (const sentiment of sentiments.slice(0, 20))
+            lines.push(`  [${stringValue(sentiment.sentiment) ?? ''}] ${(stringValue(sentiment.text) ?? '').slice(0, 80)}`);
+    }
+    const entities = arrayValue(data.entities).map(recordValue).filter((item) => Boolean(item));
+    if (entities.length > 0) {
+        lines.push('\n--- Entities ---');
+        for (const entity of entities.slice(0, 20))
+            lines.push(`  ${stringValue(entity.entity_type) ?? ''}: ${stringValue(entity.text) ?? ''}`);
+    }
+    return lines.join('\n');
+}
+function buildTranscriptBody(options, audioUrl) {
+    const body = {
+        audio_url: audioUrl,
+        speech_models: ['universal-3-pro', 'universal-2'],
+    };
+    if (options.language)
+        body.language_code = options.language;
+    else
+        body.language_detection = true;
+    if (options.speakers)
+        body.speaker_labels = true;
+    if (options.speakersExpected !== undefined) {
+        body.speaker_labels = true;
+        body.speakers_expected = options.speakersExpected;
+    }
+    if (options.speakerNames) {
+        body.speaker_labels = true;
+        body.speech_understanding = {
+            request: {
+                speaker_identification: {
+                    speaker_type: 'name',
+                    known_values: splitCommaList(options.speakerNames),
+                },
+            },
+        };
+    }
+    if (options.sentiment)
+        body.sentiment_analysis = true;
+    if (options.chapters)
+        body.auto_chapters = true;
+    if (options.entities)
+        body.entity_detection = true;
+    if (options.summarize) {
+        body.summarization = true;
+        body.summary_model = 'informative';
+        body.summary_type = 'bullets';
+    }
+    if (options.highlights)
+        body.auto_highlights = true;
+    if (options.topics)
+        body.iab_categories = true;
+    if (options.contentSafety)
+        body.content_safety = true;
+    if (options.dualChannel)
+        body.dual_channel = true;
+    if (options.multichannel)
+        body.multichannel = true;
+    if (options.wordBoost) {
+        body.word_boost = splitCommaList(options.wordBoost);
+        body.boost_param = 'high';
+    }
+    if (options.disfluencies)
+        body.disfluencies = true;
+    if (options.filterProfanity)
+        body.filter_profanity = true;
+    if (options.redactPii) {
+        body.redact_pii = true;
+        body.redact_pii_policies = ['email_address', 'phone_number', 'person_name', 'location', 'date_of_birth', 'credit_card_number'];
+    }
+    return body;
+}
+async function uploadLocalAudio(path) {
+    const content = await readLocalFile(path);
+    const explicitKey = process.env.ASSEMBLYAI_API_KEY;
+    if (explicitKey)
+        return { audioUrl: await uploadWithKey(content, explicitKey), credential: { apiKey: explicitKey } };
+    try {
+        const response = await callWithRetry('assemblyai', async (key) => ({ audioUrl: await uploadWithKey(content, key.apiKey, key.baseUrl), credential: fromVendedKey(key) }));
+        if (response)
+            return response;
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.name === 'ServiceCallError'))
+            throw error;
+        throw new EscliError(error.message, { code: ErrorCode.AudioUploadFailed, details: error.message });
+    }
+    throw missingCredentialError();
+}
+async function uploadWithKey(content, apiKey, baseUrl) {
+    const response = await requestJson({ method: 'POST', path: '/v2/upload', apiKey, baseUrl, content, timeoutMs: DEFAULT_UPLOAD_TIMEOUT_MS });
+    const uploadUrl = stringValue(response.upload_url);
+    if (!uploadUrl)
+        throw new EscliError('invalid AssemblyAI upload response: missing upload_url', { code: ErrorCode.GateInvalidResponse, details: response });
+    return uploadUrl;
+}
+async function readLocalFile(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT')
+            throw new EscliError(`file not found: ${path}`, { code: ErrorCode.FileNotFound, details: { path } });
+        throw new EscliError(`failed to read file: ${path}`, { code: ErrorCode.FileReadFailed, details: error instanceof Error ? error.message : error });
+    }
+}
+async function resolveAssemblyAiCredential() {
+    if (process.env.ASSEMBLYAI_API_KEY)
+        return { apiKey: process.env.ASSEMBLYAI_API_KEY };
+    const key = await vendKeyForService('assemblyai');
+    if (key?.apiKey)
+        return fromVendedKey(key);
+    throw missingCredentialError();
+}
+async function fetchTranscriptWithCredential(transcriptId) {
+    if (process.env.ASSEMBLYAI_API_KEY) {
+        const credential = { apiKey: process.env.ASSEMBLYAI_API_KEY };
+        return { transcript: await requestTranscript(transcriptId, credential), credential };
+    }
+    const remembered = await readRememberedTranscriptCredential(transcriptId);
+    if (remembered)
+        return { transcript: await requestTranscript(transcriptId, remembered), credential: remembered };
+    let notFound;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        const key = await vendKeyForService('assemblyai');
+        if (!key)
+            break;
+        const credential = fromVendedKey(key);
+        try {
+            return { transcript: await requestTranscript(transcriptId, credential), credential };
+        }
+        catch (error) {
+            if (error instanceof EscliError && error.code === ErrorCode.AudioTranscriptNotFound) {
+                notFound = error;
+                continue;
+            }
+            throw error;
+        }
+    }
+    if (notFound)
+        throw notFound;
+    throw missingCredentialError();
+}
+function requestTranscript(transcriptId, credential) {
+    return requestJson({ method: 'GET', path: `/v2/transcript/${encodeURIComponent(transcriptId)}`, apiKey: credential.apiKey, baseUrl: credential.baseUrl });
+}
+async function rememberTranscriptCredential(transcriptId, credential) {
+    if (process.env.ASSEMBLYAI_API_KEY)
+        return;
+    const entries = await readRememberedTranscriptCredentials();
+    entries[transcriptId] = credential;
+    await mkdir(cacheDir(), { recursive: true });
+    await writeFile(transcriptCredentialCachePath(), `${JSON.stringify(entries, null, 2)}\n`);
+    await chmod(transcriptCredentialCachePath(), 0o600);
+}
+async function readRememberedTranscriptCredential(transcriptId) {
+    return readRememberedTranscriptCredentials().then((entries) => entries[transcriptId]);
+}
+async function readRememberedTranscriptCredentials() {
+    try {
+        const parsed = JSON.parse(await readFile(transcriptCredentialCachePath(), 'utf8'));
+        return recordValue(parsed) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function transcriptCredentialCachePath() {
+    return join(cacheDir(), 'audio-transcripts.json');
+}
+function cacheDir() {
+    return process.env.ESCLI_CACHE_DIR ?? join(homedir(), '.escli', 'cache');
+}
+function fromVendedKey(key) {
+    return { apiKey: key.apiKey, baseUrl: key.baseUrl };
+}
+function missingCredentialError() {
+    return new EscliError('no AssemblyAI API key. Set ASSEMBLYAI_API_KEY or add one via the dashboard.', {
+        code: ErrorCode.AuthRequired,
+        exitCode: ExitCodes.Auth,
+        remediation: { hint: 'Set ASSEMBLYAI_API_KEY or authenticate with a profile that can vend assemblyai keys.' },
+    });
+}
+async function pollTranscript(transcriptId, credential) {
+    for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
+        const data = await requestJson({ method: 'GET', path: `/v2/transcript/${encodeURIComponent(transcriptId)}`, apiKey: credential.apiKey, baseUrl: credential.baseUrl });
+        if (data.status === 'completed' || data.status === 'error')
+            return data;
+        await sleep(pollIntervalMs());
+    }
+    throw new EscliError('transcription polling timed out', { code: ErrorCode.NetworkTimeout, details: { id: transcriptId } });
+}
+async function requestJson(options) {
+    const text = await requestText(options);
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`invalid JSON response: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.GateInvalidResponse,
+            details: text,
+        });
+    }
+}
+async function requestText(options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${assemblyAiBaseUrl(options.baseUrl)}${options.path}`, {
+            method: options.method,
+            headers: requestHeaders(options.apiKey, Boolean(options.jsonBody)),
+            body: options.jsonBody ? JSON.stringify(options.jsonBody) : options.content,
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw httpStatusError(response.status, formatHttpError(response.status, text), text);
+        return text;
+    }
+    catch (error) {
+        if (isHttpStatusError(error))
+            throw mapHttpStatusError(error);
+        throw mapNetworkError(error);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function requestHeaders(apiKey, hasJsonBody) {
+    const headers = { Authorization: apiKey };
+    if (hasJsonBody)
+        headers['Content-Type'] = 'application/json';
+    return headers;
+}
+function httpStatusError(status, message, details) {
+    const error = new Error(message);
+    error.status = status;
+    error.details = details;
+    return error;
+}
+function isHttpStatusError(error) {
+    return error instanceof Error && typeof error.status === 'number';
+}
+function mapHttpStatusError(error) {
+    const status = error.status;
+    if (status === 401)
+        return new EscliError(error.message, { code: ErrorCode.ApiUnauthorized, details: error.details });
+    if (status === 403)
+        return new EscliError(error.message, { code: ErrorCode.ApiForbidden, details: error.details });
+    if (status === 404)
+        return new EscliError(error.message, { code: ErrorCode.AudioTranscriptNotFound, details: error.details });
+    if (status === 429)
+        return new EscliError(error.message, { code: ErrorCode.ApiRateLimited, details: error.details });
+    if (status >= 500)
+        return new EscliError(error.message, { code: ErrorCode.ServiceUnavailable, details: error.details });
+    return new EscliError(error.message, { code: ErrorCode.ApiError, details: error.details });
+}
+function mapNetworkError(error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError';
+    return new EscliError(isAbort ? 'network error: request timed out' : `network error: ${error instanceof Error ? error.message : String(error)}`, {
+        code: isAbort ? ErrorCode.NetworkTimeout : ErrorCode.NetworkError,
+        details: error instanceof Error ? error.message : error,
+    });
+}
+async function writeOutputFile(path, content) {
+    const { writeFile } = await import('node:fs/promises');
+    try {
+        await writeFile(path, content);
+    }
+    catch (error) {
+        throw new EscliError(`failed to write file: ${path}`, { code: ErrorCode.FileWriteFailed, details: error instanceof Error ? error.message : error });
+    }
+}
+function summarizeTranscript(transcript, elapsedSeconds) {
+    const utterances = Array.isArray(transcript.utterances) ? transcript.utterances : [];
+    return {
+        id: transcript.id,
+        elapsed_seconds: elapsedSeconds,
+        text: stringValue(transcript.text) ?? '',
+        speakers: new Set(utterances.map((utterance) => stringValue(utterance.speaker) ?? '')).size,
+        words: Array.isArray(transcript.words) ? transcript.words : [],
+        utterances,
+    };
+}
+function formatHttpError(status, body) {
+    const parsed = parseMaybeJson(body);
+    const message = extractErrorMessage(parsed) ?? (typeof parsed === 'string' ? parsed : undefined);
+    return message ? `API error (${status}): ${message}` : `API error (${status})`;
+}
+function parseMaybeJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function extractErrorMessage(body) {
+    const root = recordValue(body);
+    return stringValue(root?.error) ?? stringValue(root?.message) ?? stringValue(recordValue(root?.error)?.message);
+}
+function assemblyAiBaseUrl(baseUrl) {
+    if (baseUrl)
+        return baseUrl.replace(/\/+$/u, '');
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_ASSEMBLYAI_URL)
+        return process.env.ESCLI_TEST_ASSEMBLYAI_URL;
+    return ASSEMBLYAI_BASE_URL;
+}
+function pollIntervalMs() {
+    if (typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) {
+        const value = Number(process.env.ESCLI_AUDIO_POLL_INTERVAL_MS);
+        if (Number.isFinite(value) && value >= 0)
+            return Math.trunc(value);
+    }
+    return DEFAULT_POLL_INTERVAL_MS;
+}
+function isRemoteUrl(value) {
+    return value.startsWith('http://') || value.startsWith('https://');
+}
+function splitCommaList(value) {
+    return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function roundElapsed(seconds) {
+    return Math.round(seconds * 10) / 10;
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=audio.js.map