@ericdisero/aurora-shared 0.1.0

package/dist/paths.d.ts

@@ -0,0 +1,17 @@
+import type { AppSettings } from './types.js';
+/** Aurora's userData directory. AURORA_USER_DATA overrides (also how the test
+ *  harness isolates); otherwise the per-OS Electron location, preferring the
+ *  casing variant that already holds aurora.db. */
+export declare function getUserDataDir(): string;
+export declare function getDbPath(): string;
+/** Read the app's settings.json, merging saved values over defaults (the app's
+ *  own semantics — missing keys fall to default). Read-only here: the MCP never
+ *  writes settings. */
+export declare function getSettings(): AppSettings;
+/** Active projects root — the custom setting if set, else userData/projects. */
+export declare function getProjectsDirectory(): string;
+/** Global reference library dir (userData/references/<refId>/ holds the copied
+ *  audio + cached curve files). */
+export declare function getReferencesDir(): string;
+/** Where MCP background-job manifests live. */
+export declare function getJobsDir(): string;

package/dist/paths.js

@@ -0,0 +1,79 @@
+// Aurora userData + project-root resolution WITHOUT Electron. The desktop app
+// resolves these via app.getPath('userData'); we hardcode-resolve the same
+// locations per OS (the handoff plan's blessed approach). The app's Electron
+// name is `aurora` (package.json name) in dev and productName `Aurora` when
+// packaged — same directory on the case-insensitive default filesystems of
+// Windows/macOS; on Linux we probe both casings and prefer the one holding
+// aurora.db.
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const SETTINGS_DEFAULTS = {
+    projectsDirectory: '',
+    outputDirectory: '',
+    defaultGenModel: 'V5',
+    defaultSmoothing: 0.5,
+    defaultBitDepth: 24
+};
+function userDataCandidates() {
+    const home = homedir();
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+        return [join(appData, 'aurora'), join(appData, 'Aurora')];
+    }
+    if (process.platform === 'darwin') {
+        const base = join(home, 'Library', 'Application Support');
+        return [join(base, 'aurora'), join(base, 'Aurora')];
+    }
+    const base = process.env.XDG_CONFIG_HOME || join(home, '.config');
+    return [join(base, 'aurora'), join(base, 'Aurora')];
+}
+/** Aurora's userData directory. AURORA_USER_DATA overrides (also how the test
+ *  harness isolates); otherwise the per-OS Electron location, preferring the
+ *  casing variant that already holds aurora.db. */
+export function getUserDataDir() {
+    if (process.env.AURORA_USER_DATA)
+        return process.env.AURORA_USER_DATA;
+    const candidates = userDataCandidates();
+    for (const c of candidates) {
+        if (existsSync(join(c, 'aurora.db')))
+            return c;
+    }
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return candidates[0];
+}
+export function getDbPath() {
+    return join(getUserDataDir(), 'aurora.db');
+}
+/** Read the app's settings.json, merging saved values over defaults (the app's
+ *  own semantics — missing keys fall to default). Read-only here: the MCP never
+ *  writes settings. */
+export function getSettings() {
+    const path = join(getUserDataDir(), 'settings.json');
+    if (!existsSync(path))
+        return { ...SETTINGS_DEFAULTS };
+    try {
+        const saved = JSON.parse(readFileSync(path, 'utf-8'));
+        return { ...SETTINGS_DEFAULTS, ...saved };
+    }
+    catch {
+        return { ...SETTINGS_DEFAULTS };
+    }
+}
+/** Active projects root — the custom setting if set, else userData/projects. */
+export function getProjectsDirectory() {
+    return getSettings().projectsDirectory || join(getUserDataDir(), 'projects');
+}
+/** Global reference library dir (userData/references/<refId>/ holds the copied
+ *  audio + cached curve files). */
+export function getReferencesDir() {
+    return join(getUserDataDir(), 'references');
+}
+/** Where MCP background-job manifests live. */
+export function getJobsDir() {
+    return join(getUserDataDir(), 'agent-jobs');
+}
+//# sourceMappingURL=paths.js.map

package/dist/providers/mvsep.d.ts

@@ -0,0 +1,27 @@
+import type { MvsepJobSpec, SeparationResultFile } from '../types.js';
+export declare const MVSEP_BASE_URL = "https://mvsep.com";
+/** Submit one separation job (multipart, field MUST be "audiofile"). */
+export declare function createSeparationJob(audio: Buffer, spec: MvsepJobSpec): Promise<{
+    hash: string;
+}>;
+export interface SeparationStatus {
+    /** waiting | processing | distributing | merging | done | failed | not_found */
+    status: string;
+    files?: SeparationResultFile[];
+    message?: string;
+}
+/** ONE status fetch (no waiting) — the background-job model's poll unit. */
+export declare function fetchSeparationStatus(hash: string): Promise<SeparationStatus>;
+/** Interpret a status: returns files when done, null while in flight, throws on
+ *  terminal failure. */
+export declare function resolveSeparationStatus(hash: string, s: SeparationStatus): SeparationResultFile[] | null;
+/** Blocking poll until the job is done; returns the result files. */
+export declare function awaitSeparationResult(handle: {
+    hash: string;
+}, onPoll?: (status: string) => void): Promise<SeparationResultFile[]>;
+export interface MvsepUserInfo {
+    premiumMinutes: number | null;
+    premiumEnabled: boolean | null;
+}
+/** Free balance call — premium minutes + premium flag from /api/app/user. */
+export declare function getMvsepUserInfo(): Promise<MvsepUserInfo>;

package/dist/providers/mvsep.js

@@ -0,0 +1,112 @@
+// MVSEP client — port of aurora's verified implementation (src/main/providers/
+// separation/dev-direct.ts), re-verified against live mvsep.com docs +
+// GET /api/app/algorithms on 2026-06-10. Adds a single-shot status fetch for
+// the background-job model and the free user-info balance call.
+// Contract: aurora/docs/build-specs/mvsep-separation-contract.md.
+import { requireMvsepKey } from '../config.js';
+export const MVSEP_BASE_URL = 'https://mvsep.com';
+const CREATE_URL = `${MVSEP_BASE_URL}/api/separation/create`;
+const GET_URL = `${MVSEP_BASE_URL}/api/separation/get`;
+const USER_URL = `${MVSEP_BASE_URL}/api/app/user`;
+const MAX_RETRIES = 5;
+const BASE_RETRY_DELAY_MS = 3000; // exp backoff: 3 * 2**(r-1) seconds
+const POLL_DELAY_MS = 5000;
+const MAX_POLL_ATTEMPTS = 120; // ~10 min ceiling
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Submit one separation job (multipart, field MUST be "audiofile"). */
+export async function createSeparationJob(audio, spec) {
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const form = new FormData();
+            form.append('api_token', requireMvsepKey());
+            form.append('sep_type', spec.sep_type);
+            form.append('output_format', spec.output_format);
+            form.append('is_demo', spec.is_demo);
+            if (spec.add_opt1 != null)
+                form.append('add_opt1', spec.add_opt1);
+            if (spec.add_opt2 != null)
+                form.append('add_opt2', spec.add_opt2);
+            const blob = new Blob([new Uint8Array(audio)], { type: 'audio/wav' });
+            form.append('audiofile', blob, 'input.wav');
+            const res = await fetch(CREATE_URL, { method: 'POST', body: form });
+            const body = (await res.json());
+            if (!res.ok || !body.success || !body.data?.hash) {
+                throw new Error(`MVSEP create failed (HTTP ${res.status}): ${body.data?.message || 'unknown error'}`);
+            }
+            return { hash: body.data.hash };
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * 2 ** (attempt - 1));
+            }
+        }
+    }
+    throw new Error(`MVSEP create failed after ${MAX_RETRIES} attempts: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+/** ONE status fetch (no waiting) — the background-job model's poll unit. */
+export async function fetchSeparationStatus(hash) {
+    const res = await fetch(`${GET_URL}?hash=${encodeURIComponent(hash)}`);
+    const body = (await res.json());
+    const status = body.status ?? 'unknown';
+    return {
+        status,
+        files: body.data?.files?.map((f) => ({ url: f.url, filename: f.download })),
+        message: body.data?.message
+    };
+}
+/** Interpret a status: returns files when done, null while in flight, throws on
+ *  terminal failure. */
+export function resolveSeparationStatus(hash, s) {
+    switch (s.status) {
+        case 'done':
+            if (!s.files || s.files.length === 0) {
+                throw new Error(`MVSEP job ${hash} is done but returned no result files — results are deleted server-side ` +
+                    'after a retention window; the job likely expired before download. Re-run the split.');
+            }
+            return s.files;
+        case 'failed':
+            throw new Error(`MVSEP job failed: ${s.message || 'no detail'}`);
+        case 'not_found':
+            throw new Error(`MVSEP job not found (hash invalid, expired, or result already deleted): ${hash}`);
+        case 'waiting':
+        case 'processing':
+        case 'distributing':
+        case 'merging':
+            return null;
+        default:
+            throw new Error(`MVSEP unknown job status: ${s.status}`);
+    }
+}
+/** Blocking poll until the job is done; returns the result files. */
+export async function awaitSeparationResult(handle, onPoll) {
+    for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+        await sleep(POLL_DELAY_MS);
+        let s;
+        try {
+            s = await fetchSeparationStatus(handle.hash);
+        }
+        catch {
+            continue; // transient network blip — keep polling
+        }
+        onPoll?.(s.status);
+        const files = resolveSeparationStatus(handle.hash, s);
+        if (files)
+            return files;
+    }
+    throw new Error('MVSEP job timed out (exceeded ~10 min poll ceiling)');
+}
+/** Free balance call — premium minutes + premium flag from /api/app/user. */
+export async function getMvsepUserInfo() {
+    const res = await fetch(`${USER_URL}?api_token=${encodeURIComponent(requireMvsepKey())}`);
+    const body = (await res.json());
+    if (!res.ok || body.success === false) {
+        throw new Error(`MVSEP user info failed (HTTP ${res.status})`);
+    }
+    return {
+        premiumMinutes: body.data?.premium_minutes ?? null,
+        premiumEnabled: body.data?.premium_enabled != null ? body.data.premium_enabled === 1 : null
+    };
+}
+//# sourceMappingURL=mvsep.js.map

package/dist/providers/suno.d.ts

@@ -0,0 +1,89 @@
+export declare const SUNOAPI_BASE_URL = "https://api.sunoapi.org";
+export declare const KIE_BASE_URL = "https://api.kie.ai";
+export interface SunoProvider {
+    label: string;
+    baseUrl: string;
+    apiKey: string;
+    uploadStreamUrls: string[];
+}
+/** Resolve the active provider. Base URL: override → sunoapi.org when its key
+ *  is set → kie.ai. Key: SUNO_API_KEY falling back to KIE_API_KEY. */
+export declare function getProvider(): SunoProvider;
+export declare const host: () => string;
+export interface GenerationParams {
+    prompt: string;
+    style?: string;
+    title?: string;
+    instrumental: boolean;
+    customMode: boolean;
+    model: string;
+    vocalGender?: 'male' | 'female';
+    /** Comma-separated styles to exclude (the docs type this as ONE string). */
+    negativeTags?: string;
+}
+/** Submit a generation task. Returns the provider taskId. */
+export declare function createGeneration(params: GenerationParams): Promise<string>;
+export interface SoundsParams {
+    /** Max 500 chars per docs.sunoapi.org/suno-api/generate-sounds. */
+    prompt: string;
+    /** Pitch lock, e.g. 'C', 'Cm', 'F#'. Default 'Any'. */
+    soundKey?: string;
+    /** BPM 1-300; omit for auto. */
+    soundTempo?: number;
+    soundLoop?: boolean;
+}
+/** Submit a Sounds Generation task. sunoapi.org ONLY — kie.ai does not expose
+ *  the endpoint. Model locked to V5 by the docs. */
+export declare function createSoundsGeneration(params: SoundsParams): Promise<string>;
+/** Upload a local audio file via the provider's File Upload API. Returns the
+ *  hosted URL for use as a cover reference (auto-deletes after ~3 days). */
+export declare function uploadAudioFile(filePath: string): Promise<string>;
+export interface CoverParams {
+    /** Hosted reference-audio URL from uploadAudioFile. */
+    uploadUrl: string;
+    prompt: string;
+    style?: string;
+    title?: string;
+    instrumental: boolean;
+    customMode: boolean;
+    model: string;
+    vocalGender?: 'male' | 'female';
+    negativeTags?: string;
+    /** 0..1 — how strongly the output hews to the input audio. */
+    audioWeight?: number;
+}
+/** Submit an upload-and-cover (style transform) task. Poll the returned taskId
+ *  with the generation record fetchers (same record-info endpoint). */
+export declare function createCover(params: CoverParams): Promise<string>;
+export interface PolledVariation {
+    /** Per-variation audio id — the WAV-conversion stage needs it. */
+    id?: string;
+    audioUrl?: string;
+    /** Listenable mid-generation, before audioUrl exists. Expires server-side —
+     *  never persist; use for instant preview only. */
+    streamAudioUrl?: string;
+    title?: string;
+    duration?: number;
+}
+export interface GenerationRecord {
+    /** PENDING / TEXT_SUCCESS / FIRST_SUCCESS / SUCCESS / *_FAILED /
+     *  CALLBACK_EXCEPTION / SENSITIVE_WORD_ERROR */
+    status: string;
+    variations: PolledVariation[];
+}
+/** ONE record-info fetch (no waiting). The background-job model's poll unit. */
+export declare function fetchGenerationRecord(taskId: string): Promise<GenerationRecord>;
+export declare function isGenerationFailure(status: string): boolean;
+/** Blocking poll until the variations are ready (mirrors the app's pattern,
+ *  including the CALLBACK_EXCEPTION grace window). */
+export declare function pollGenerationTask(taskId: string, onStatus?: (status: string) => void): Promise<PolledVariation[]>;
+/** Submit a WAV conversion for one variation. Returns the WAV task's own taskId. */
+export declare function createWavConversion(taskId: string, audioId: string): Promise<string>;
+/** Blocking poll of wav/record-info until the WAV URL appears. Tolerant of
+ *  shape drift (camel/snake, nested/flat). */
+export declare function pollWavConversion(wavTaskId: string): Promise<string>;
+/** Download a URL to disk. Provider URLs expire server-side — always persist
+ *  immediately. */
+export declare function downloadTo(url: string, destPath: string): Promise<void>;
+/** Remaining credit balance — free call, doubles as the auth smoke test. */
+export declare function getRemainingCredits(): Promise<number>;

package/dist/providers/suno.js

@@ -0,0 +1,309 @@
+// Suno-provider client — sunoapi.org PRIMARY, kie.ai fallback (schema-identical
+// /api/v1/* surfaces). Merged port of aurora's two proven implementations:
+// src/main/providers/generation/suno-client.ts (app) + tools/bridge/lib/kie.ts
+// (the reference impl, real-call verified 2026-06-10). Adds single-shot record
+// fetchers so the background-job model can poll without blocking, and surfaces
+// streamAudioUrl (listenable mid-generation, before the final file exists).
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { getKieKey, getSunoBaseUrlOverride, getSunoKey } from '../config.js';
+export const SUNOAPI_BASE_URL = 'https://api.sunoapi.org';
+export const KIE_BASE_URL = 'https://api.kie.ai';
+/** Resolve the active provider. Base URL: override → sunoapi.org when its key
+ *  is set → kie.ai. Key: SUNO_API_KEY falling back to KIE_API_KEY. */
+export function getProvider() {
+    const sunoKey = getSunoKey();
+    const kieKey = getKieKey();
+    const apiKey = sunoKey || kieKey;
+    if (!apiKey) {
+        throw new Error('No Suno provider key configured. Set SUNO_API_KEY (api.sunoapi.org, primary) or ' +
+            'KIE_API_KEY (api.kie.ai, fallback) in your environment / MCP config env block, ' +
+            'or run: aurora keys set --suno-api-key <key>');
+    }
+    const baseUrl = getSunoBaseUrlOverride() || (sunoKey ? SUNOAPI_BASE_URL : KIE_BASE_URL);
+    const isSunoApiOrg = baseUrl.includes('sunoapi.org');
+    return {
+        label: isSunoApiOrg ? 'sunoapi.org' : new URL(baseUrl).host,
+        baseUrl,
+        apiKey,
+        uploadStreamUrls: isSunoApiOrg
+            ? ['https://sunoapiorg.redpandaai.co/api/file-stream-upload', `${baseUrl}/api/file-stream-upload`]
+            : ['https://kieai.redpandaai.co/api/file-stream-upload', `${baseUrl}/api/file-stream-upload`]
+    };
+}
+function authHeaders() {
+    return {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${getProvider().apiKey}`
+    };
+}
+const api = (path) => `${getProvider().baseUrl}${path}`;
+export const host = () => getProvider().label;
+// Placeholder used only if the provider rejects a create that omits callBackUrl.
+// We never receive this callback — completion is detected by polling.
+const CALLBACK_PLACEHOLDER = 'https://example.com/aurora-mcp-callback';
+const POLL_DELAY_MS = 5000;
+const MAX_POLL_ATTEMPTS = 120; // ~10 min ceiling
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const wireVocalGender = (v) => (v === 'male' ? 'm' : 'f');
+/** Submit a generation task. Returns the provider taskId. */
+export async function createGeneration(params) {
+    const body = {
+        prompt: params.prompt,
+        customMode: params.customMode,
+        instrumental: params.instrumental,
+        model: params.model
+    };
+    if (params.style)
+        body.style = params.style;
+    if (params.title)
+        body.title = params.title;
+    if (params.vocalGender)
+        body.vocalGender = wireVocalGender(params.vocalGender);
+    if (params.negativeTags)
+        body.negativeTags = params.negativeTags;
+    const res = await fetch(api('/api/v1/generate'), {
+        method: 'POST',
+        headers: authHeaders(),
+        body: JSON.stringify(body)
+    });
+    const json = (await res.json());
+    const taskId = json.data?.taskId;
+    if (!res.ok || !taskId) {
+        throw new Error(`${host()} generate failed (HTTP ${res.status}): ${json.msg || 'no taskId returned'}`);
+    }
+    return taskId;
+}
+/** Submit a Sounds Generation task. sunoapi.org ONLY — kie.ai does not expose
+ *  the endpoint. Model locked to V5 by the docs. */
+export async function createSoundsGeneration(params) {
+    const body = { prompt: params.prompt, model: 'V5' };
+    if (params.soundKey)
+        body.soundKey = params.soundKey;
+    if (params.soundTempo !== undefined)
+        body.soundTempo = params.soundTempo;
+    if (params.soundLoop)
+        body.soundLoop = true;
+    const res = await fetch(api('/api/v1/generate/sounds'), {
+        method: 'POST',
+        headers: authHeaders(),
+        body: JSON.stringify(body)
+    });
+    const json = (await res.json());
+    const taskId = json.data?.taskId ?? json.data?.task_id;
+    if (!res.ok || (json.code !== undefined && json.code !== 200) || !taskId) {
+        throw new Error(`${host()} generate/sounds failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no taskId returned'}`);
+    }
+    return taskId;
+}
+// ── Upload + cover (style transform) ────────────────────────────
+const MIME_BY_EXT = {
+    '.wav': 'audio/wav',
+    '.mp3': 'audio/mpeg',
+    '.flac': 'audio/flac',
+    '.aiff': 'audio/aiff',
+    '.aif': 'audio/aiff'
+};
+const UPLOAD_DIR = 'aurora-mcp';
+/** Upload a local audio file via the provider's File Upload API. Returns the
+ *  hosted URL for use as a cover reference (auto-deletes after ~3 days). */
+export async function uploadAudioFile(filePath) {
+    const { apiKey, uploadStreamUrls } = getProvider();
+    const bytes = await readFile(filePath);
+    const fileName = basename(filePath);
+    const mime = MIME_BY_EXT[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+    let lastError;
+    for (const url of uploadStreamUrls) {
+        try {
+            const form = new FormData();
+            form.append('uploadPath', UPLOAD_DIR);
+            form.append('fileName', fileName);
+            form.append('file', new Blob([new Uint8Array(bytes)], { type: mime }), fileName);
+            const res = await fetch(url, {
+                method: 'POST',
+                // No Content-Type — fetch sets the multipart boundary itself.
+                headers: { Authorization: `Bearer ${apiKey}` },
+                body: form
+            });
+            const json = (await res.json());
+            const hosted = json.data?.downloadUrl ?? json.data?.download_url ?? json.data?.fileUrl ?? json.data?.file_url;
+            if (!res.ok || json.success === false || (json.code !== undefined && json.code !== 200) || !hosted) {
+                throw new Error(`${host()} file upload failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no downloadUrl returned'}`);
+            }
+            return hosted;
+        }
+        catch (err) {
+            lastError = err; // try the fallback host
+        }
+    }
+    throw new Error(`${host()} file upload failed on all hosts: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+/** Submit an upload-and-cover (style transform) task. Poll the returned taskId
+ *  with the generation record fetchers (same record-info endpoint). */
+export async function createCover(params) {
+    const attempt = async (withCallback) => {
+        const body = {
+            uploadUrl: params.uploadUrl,
+            prompt: params.prompt,
+            customMode: params.customMode,
+            instrumental: params.instrumental,
+            model: params.model
+        };
+        if (params.style)
+            body.style = params.style;
+        if (params.title)
+            body.title = params.title;
+        if (params.vocalGender)
+            body.vocalGender = wireVocalGender(params.vocalGender);
+        if (params.negativeTags)
+            body.negativeTags = params.negativeTags;
+        if (params.audioWeight !== undefined)
+            body.audioWeight = params.audioWeight;
+        if (withCallback)
+            body.callBackUrl = CALLBACK_PLACEHOLDER;
+        const res = await fetch(api('/api/v1/generate/upload-cover'), {
+            method: 'POST',
+            headers: authHeaders(),
+            body: JSON.stringify(body)
+        });
+        const json = (await res.json());
+        const taskId = json.data?.taskId ?? json.data?.task_id;
+        if (!res.ok || (json.code !== undefined && json.code !== 200) || !taskId) {
+            throw new Error(`${host()} upload-cover failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no taskId returned'}`);
+        }
+        return taskId;
+    };
+    try {
+        return await attempt(false);
+    }
+    catch {
+        return attempt(true);
+    }
+}
+/** ONE record-info fetch (no waiting). The background-job model's poll unit. */
+export async function fetchGenerationRecord(taskId) {
+    const res = await fetch(`${api('/api/v1/generate/record-info')}?taskId=${encodeURIComponent(taskId)}`, { headers: authHeaders() });
+    const info = (await res.json());
+    const status = info.data?.status ?? 'PENDING';
+    const variations = (info.data?.response?.sunoData ?? []).map((s) => ({
+        id: s.id,
+        audioUrl: s.audioUrl,
+        streamAudioUrl: s.streamAudioUrl,
+        title: s.title,
+        duration: s.duration
+    }));
+    return { status, variations };
+}
+export function isGenerationFailure(status) {
+    return status.endsWith('FAILED') || status === 'CREATE_TASK_FAILED' || status === 'SENSITIVE_WORD_ERROR';
+}
+/** Blocking poll until the variations are ready (mirrors the app's pattern,
+ *  including the CALLBACK_EXCEPTION grace window). */
+export async function pollGenerationTask(taskId, onStatus) {
+    let terminalWithoutAudio = 0;
+    for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+        await sleep(POLL_DELAY_MS);
+        let record;
+        try {
+            record = await fetchGenerationRecord(taskId);
+        }
+        catch {
+            continue; // transient — keep polling
+        }
+        onStatus?.(record.status);
+        if (record.status === 'SUCCESS' || record.status === 'CALLBACK_EXCEPTION') {
+            const ready = record.variations.filter((v) => v.audioUrl);
+            if (ready.length > 0)
+                return ready;
+            if (record.status === 'SUCCESS') {
+                throw new Error(`${host()} reported SUCCESS but returned no audio URLs`);
+            }
+            terminalWithoutAudio++;
+            if (terminalWithoutAudio >= 3) {
+                throw new Error(`${host()} reported CALLBACK_EXCEPTION but returned no audio URLs`);
+            }
+            continue;
+        }
+        if (isGenerationFailure(record.status)) {
+            throw new Error(`${host()} generation failed with status: ${record.status}`);
+        }
+    }
+    throw new Error(`${host()} generation timed out (exceeded ~10 min poll ceiling)`);
+}
+// ── WAV conversion ──────────────────────────────────────────────
+/** Submit a WAV conversion for one variation. Returns the WAV task's own taskId. */
+export async function createWavConversion(taskId, audioId) {
+    const attempt = async (withCallback) => {
+        const body = { taskId, audioId };
+        if (withCallback)
+            body.callBackUrl = CALLBACK_PLACEHOLDER;
+        const res = await fetch(api('/api/v1/wav/generate'), {
+            method: 'POST',
+            headers: authHeaders(),
+            body: JSON.stringify(body)
+        });
+        const json = (await res.json());
+        const wavTaskId = json.data?.taskId ?? json.data?.task_id;
+        if (!res.ok || (json.code !== undefined && json.code !== 200) || !wavTaskId) {
+            throw new Error(`${host()} wav/generate failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no taskId returned'}`);
+        }
+        return wavTaskId;
+    };
+    try {
+        return await attempt(false);
+    }
+    catch {
+        return attempt(true);
+    }
+}
+/** Blocking poll of wav/record-info until the WAV URL appears. Tolerant of
+ *  shape drift (camel/snake, nested/flat). */
+export async function pollWavConversion(wavTaskId) {
+    let terminalWithoutUrl = 0;
+    for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+        await sleep(POLL_DELAY_MS);
+        let json;
+        try {
+            const res = await fetch(`${api('/api/v1/wav/record-info')}?taskId=${encodeURIComponent(wavTaskId)}`, { headers: authHeaders() });
+            json = (await res.json());
+        }
+        catch {
+            continue;
+        }
+        const d = json.data ?? {};
+        const url = d.response?.audioWavUrl ?? d.response?.audio_wav_url ?? d.audioWavUrl ?? d.audio_wav_url;
+        if (typeof url === 'string' && url.length > 0)
+            return url;
+        const flag = String(d.successFlag ?? d.status ?? 'PENDING');
+        if (flag.endsWith('FAILED')) {
+            throw new Error(`${host()} WAV conversion failed (${flag}): ${d.errorMessage || d.errorCode || 'no detail'}`);
+        }
+        if (flag === 'SUCCESS' || flag === 'CALLBACK_EXCEPTION') {
+            terminalWithoutUrl++;
+            if (terminalWithoutUrl >= 3) {
+                throw new Error(`${host()} WAV task reports ${flag} but no audioWavUrl returned`);
+            }
+        }
+    }
+    throw new Error(`${host()} WAV conversion timed out (exceeded ~10 min poll ceiling)`);
+}
+// ── Misc ────────────────────────────────────────────────────────
+/** Download a URL to disk. Provider URLs expire server-side — always persist
+ *  immediately. */
+export async function downloadTo(url, destPath) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Download failed (HTTP ${res.status}): ${url}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    await writeFile(destPath, buf);
+}
+/** Remaining credit balance — free call, doubles as the auth smoke test. */
+export async function getRemainingCredits() {
+    const res = await fetch(api('/api/v1/generate/credit'), { headers: authHeaders() });
+    const json = (await res.json());
+    if (!res.ok || (json.code !== undefined && json.code !== 200) || typeof json.data !== 'number') {
+        throw new Error(`${host()} credit check failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no numeric data field'}`);
+    }
+    return json.data;
+}
+//# sourceMappingURL=suno.js.map

package/dist/sidecars.d.ts

@@ -0,0 +1,20 @@
+export interface RvcUpscaleParams {
+    /** Input vocal WAV (typically the split's vocals stem). */
+    inputPath: string;
+    /** Output WAV path. */
+    outputPath: string;
+    /** Voice model: 'jb' (default) or 'purposeaudacity' (A/B alternate). */
+    model?: string;
+    /** Optional pitch shift in semitones. */
+    f0UpKey?: number;
+}
+export declare function runRvcUpscale(params: RvcUpscaleParams): Promise<string>;
+export type MidiMode = 'poly' | 'mono' | 'auto';
+export interface RipMidiParams {
+    inputPath: string;
+    outputPath: string;
+    /** Force a transcription path, or auto-route from `instrument`. */
+    mode: MidiMode;
+    instrument?: string;
+}
+export declare function runRipMidi(params: RipMidiParams): Promise<string>;