@jackwener/opencli 1.7.22 → 1.8.1

package/clis/suno/commands.test.js

@@ -0,0 +1,188 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+const mocks = vi.hoisted(() => ({
+    ensureSunoSession: vi.fn(),
+    checkSunoCaptcha: vi.fn(),
+}));
+
+vi.mock('./utils.js', () => ({
+    STUDIO_API: 'https://studio-api-prod.suno.com',
+    SUNO_DOMAIN: 'suno.com',
+    SUNO_URL: 'https://suno.com',
+    ensureSunoSession: mocks.ensureSunoSession,
+    checkSunoCaptcha: mocks.checkSunoCaptcha,
+    requireNonNegativeInt: (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) throw Object.assign(new Error('non-negative int required'), { code: 'ARGUMENT' });
+        return n;
+    },
+    requirePositiveInt: (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1) throw Object.assign(new Error('positive int required'), { code: 'ARGUMENT' });
+        return n;
+    },
+    unwrapEvaluateResult: (value) => value && typeof value === 'object' && 'session' in value && 'data' in value ? value.data : value,
+}));
+
+const { statusCommand } = await import('./status.js');
+const { listCommand } = await import('./list.js');
+
+function createPage(evaluateImpl) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: evaluateImpl || vi.fn().mockResolvedValue(undefined),
+    };
+}
+
+beforeEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('suno status', () => {
+    it('reports "Not logged in" when ensureSunoSession throws AuthRequiredError', async () => {
+        mocks.ensureSunoSession.mockRejectedValue(new AuthRequiredError('suno.com', 'Auth required'));
+        const out = await statusCommand.func(createPage());
+        expect(out).toEqual([{
+            Status: 'Not logged in',
+            Plan: '-',
+            Credits: '-',
+            Monthly: '-',
+            Captcha: '-',
+        }]);
+    });
+
+    it('does not hide non-auth status failures as logged-out rows', async () => {
+        mocks.ensureSunoSession.mockRejectedValue(new CommandExecutionError('malformed billing payload'));
+        await expect(statusCommand.func(createPage())).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed billing payload'),
+        });
+    });
+
+    it('returns plan / credits / captcha when the session is healthy', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({
+            ok: true,
+            planKey: 'pro',
+            planId: '3eaebef3',
+            totalCreditsAvailable: 2095,
+            breakdown: { pack: 0, purchasedPacks: 0, monthlyRemaining: 2095, monthlyLimit: 2500, monthlyUsed: 405 },
+            deviceId: 'device-uuid',
+        });
+        mocks.checkSunoCaptcha.mockResolvedValue({ ok: true, required: false });
+        const out = await statusCommand.func(createPage());
+        expect(out[0]).toMatchObject({
+            Status: 'Connected',
+            Plan: 'pro',
+            Credits: '2095',
+            Monthly: '2095/2500',
+            Captcha: 'Not required',
+        });
+    });
+
+    it('reports captcha required when /api/c/check says so', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({
+            ok: true, planKey: 'pro', planId: 'x', totalCreditsAvailable: 100,
+            breakdown: { pack: 0, purchasedPacks: 0, monthlyRemaining: 100, monthlyLimit: 2500, monthlyUsed: 2400 },
+            deviceId: 'device-uuid',
+        });
+        mocks.checkSunoCaptcha.mockResolvedValue({ ok: true, required: true });
+        const out = await statusCommand.func(createPage());
+        expect(out[0].Captcha).toContain('Required');
+    });
+});
+
+describe('suno list', () => {
+    it('returns clip rows with truncated id, title, and pagination-aware rank', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({
+            ok: true,
+            clips: [
+                { id: 'aaaaaaaa-1111-2222-3333-444444444444', title: 'Track One', status: 'complete', created_at: '2026-05-17T11:14:26.338Z' },
+                { id: 'bbbbbbbb-1111-2222-3333-444444444444', title: 'Track Two', status: 'streaming', created_at: '2026-05-17T11:00:00.000Z' },
+            ],
+        }));
+        const out = await listCommand.func(page, { limit: 10, page: 0 });
+        expect(out).toHaveLength(2);
+        expect(out[0]).toMatchObject({
+            rank: 1,
+            clip: 'aaaaaaaa',
+            title: 'Track One',
+            status: 'complete',
+            created: '2026-05-17 11:14:26',
+            link: 'https://suno.com/song/aaaaaaaa-1111-2222-3333-444444444444',
+        });
+    });
+
+    it('respects --limit (caller may receive more from feed and slice down)', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({
+            ok: true,
+            clips: [
+                { id: 'aaaaaaaa-1111-2222-3333-444444444444', title: 'A', status: 'complete', created_at: '2026-05-17T00:00:00Z' },
+                { id: 'bbbbbbbb-1111-2222-3333-444444444444', title: 'B', status: 'complete', created_at: '2026-05-17T00:00:00Z' },
+                { id: 'cccccccc-1111-2222-3333-444444444444', title: 'C', status: 'complete', created_at: '2026-05-17T00:00:00Z' },
+            ],
+        }));
+        const out = await listCommand.func(page, { limit: 2, page: 0 });
+        expect(out).toHaveLength(2);
+    });
+
+    it('rejects invalid --page instead of silently clamping to zero', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        await expect(listCommand.func(createPage(), { limit: 2, page: -1 })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+        });
+    });
+
+    it('unwraps Browser Bridge envelopes around feed rows', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({
+            session: 'browser:default',
+            data: {
+                ok: true,
+                clips: [
+                    { id: 'aaaaaaaa-1111-2222-3333-444444444444', title: 'Track One', status: 'complete', created_at: '2026-05-17T11:14:26.338Z' },
+                ],
+            },
+        }));
+        const out = await listCommand.func(page, { limit: 10, page: 0 });
+        expect(out[0].clip).toBe('aaaaaaaa');
+    });
+
+    it('returns EmptyResultError for a valid empty library response', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({ ok: true, clips: [] }));
+        await expect(listCommand.func(page, { limit: 10, page: 0 })).rejects.toMatchObject({
+            code: 'EMPTY_RESULT',
+        });
+    });
+
+    it('fails typed on malformed clip identity', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({ ok: true, clips: [{ title: 'No id' }] }));
+        await expect(listCommand.func(page, { limit: 10, page: 0 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed clip identity'),
+        });
+    });
+
+    it('surfaces feed lookup HTTP failures', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({ ok: false, status: 500 }));
+        await expect(listCommand.func(page, { limit: 5, page: 0 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('HTTP 500'),
+        });
+    });
+
+    it('surfaces malformed feed payloads as typed failures', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ deviceId: 'device-uuid' });
+        const page = createPage(vi.fn().mockResolvedValue({ ok: false, error: 'malformed clips payload' }));
+        await expect(listCommand.func(page, { limit: 5, page: 0 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed clips payload'),
+        });
+    });
+});

package/clis/suno/download.js

@@ -0,0 +1,140 @@
+/**
+ * `opencli suno download <clip-id>` — download an already-generated clip in
+ * one or more formats. Useful for grabbing assets from songs created via the
+ * Suno web UI or earlier opencli runs without re-generating.
+ *
+ * WAV downloads still trigger Suno's per-download billing (the same charge
+ * the web UI's "Download → WAV" flow makes).
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    STUDIO_API,
+    SUNO_DOMAIN,
+    SUNO_URL,
+    downloadSunoClip,
+    ensureSunoSession,
+    normalizeBooleanFlag,
+    parseFormats,
+    resolveSunoOutputDir,
+    unwrapEvaluateResult,
+} from './utils.js';
+
+import * as os from 'node:os';
+
+function displayPath(filePath) {
+    if (!filePath) return '-';
+    const home = os.homedir();
+    return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath;
+}
+
+function parseClipId(value) {
+    const raw = String(value || '').trim();
+    if (!raw) throw new ArgumentError('clip-id required (UUID or /song/<id> URL)');
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidPattern.test(raw)) return raw.toLowerCase();
+    try {
+        const parsed = new URL(raw);
+        const pathMatch = parsed.pathname.match(/^\/song\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/?$/i);
+        if (parsed.protocol === 'https:' && parsed.hostname === 'suno.com' && pathMatch) {
+            return pathMatch[1].toLowerCase();
+        }
+    } catch {}
+    throw new ArgumentError(`Invalid clip-id: ${raw}`, 'Pass a UUID or a https://suno.com/song/<uuid> URL.');
+}
+
+export const downloadCommand = cli({
+    site: 'suno',
+    name: 'download',
+    access: 'write',
+    description: 'Download an existing Suno clip (MP3 + optional WAV/M4A/video) by id',
+    domain: SUNO_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    navigateBefore: false,
+    defaultFormat: 'plain',
+    args: [
+        { name: 'clip', positional: true, required: true, help: 'Clip UUID or https://suno.com/song/<id> URL' },
+        { name: 'formats', help: 'Comma-separated formats: mp3, m4a, wav, video, cover, metadata. Default: mp3,metadata' },
+        { name: 'op', help: 'Output directory (default: ~/Music/suno)' },
+        { name: 'confirm-paid', type: 'boolean', default: false, help: 'Required to allow paid downloads (wav). Without it, paid formats are skipped with a warning.' },
+    ],
+    columns: ['status', 'clip', 'title', 'files', 'link'],
+    func: async (page, kwargs) => {
+        const clipId = parseClipId(kwargs.clip);
+        const requestedFormats = parseFormats(kwargs.formats);
+        const confirmPaid = normalizeBooleanFlag(kwargs['confirm-paid']);
+        const PAID_FORMATS = new Set(['wav']);
+        const skippedPaid = [];
+        const formats = requestedFormats.filter(f => {
+            if (PAID_FORMATS.has(f) && !confirmPaid) {
+                skippedPaid.push(f);
+                return false;
+            }
+            return true;
+        });
+        if (!formats.length) {
+            throw new ArgumentError('All requested formats require --confirm-paid true', 'Add --confirm-paid true or include a free format such as mp3 or metadata.');
+        }
+        const outputDir = resolveSunoOutputDir(kwargs.op);
+
+        const session = await ensureSunoSession(page);
+        const deviceId = session.deviceId;
+
+        // Pull the clip object from feed/v3 so audio_url/media_urls/has_stem are current.
+        const feedRes = unwrapEvaluateResult(await page.evaluate(`(async () => {
+            const browserToken = JSON.stringify({ token: btoa(JSON.stringify({ timestamp: Date.now() })) });
+            const res = await fetch('${STUDIO_API}/api/feed/v3', {
+                method: 'POST',
+                headers: {
+                    'Authorization': 'Bearer ' + (await window.Clerk.session.getToken()),
+                    'browser-token': browserToken,
+                    'device-id': ${JSON.stringify(deviceId)},
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ clip_ids: ['${clipId}'] }),
+            });
+            if (!res.ok) return { ok: false, error: 'HTTP ' + res.status };
+            const payload = await res.json().catch(() => null);
+            if (!payload || !Array.isArray(payload.clips)) return { ok: false, error: 'malformed clips payload' };
+            return { ok: true, clips: payload.clips };
+        })()`));
+
+        if (!feedRes?.ok) {
+            throw new CommandExecutionError(`Suno feed lookup failed: ${feedRes?.error || 'unknown'}`);
+        }
+        if (!Array.isArray(feedRes.clips)) {
+            throw new CommandExecutionError('Suno feed lookup returned malformed clips payload');
+        }
+        const clip = feedRes.clips.find(c => c.id === clipId);
+        if (!clip) {
+            throw new EmptyResultError('suno download', `Clip ${clipId} not found in your account. Confirm at ${SUNO_URL}/song/${clipId}.`);
+        }
+        if (clip.status !== 'complete') {
+            throw new CommandExecutionError(`Clip ${clipId} status is "${clip.status}" — not complete yet. Retry once generation finishes.`);
+        }
+
+        const result = await downloadSunoClip(page, clip, outputDir, formats, deviceId);
+        if (!result.written.some(w => w.ok)) {
+            throw new CommandExecutionError(`Suno download wrote no files for clip ${clipId}`);
+        }
+        const link = `${SUNO_URL}/song/${clip.id}`;
+        const writtenSummary = result.written
+            .map(w => w.ok ? `${w.format}:${displayPath(w.file)}` : `${w.format}:✗(${w.reason})`)
+            .join(' | ');
+        const skippedSummary = skippedPaid.length
+            ? ` | skipped(needs --confirm-paid):${skippedPaid.join(',')}`
+            : '';
+        const fileSummary = `${writtenSummary}${skippedSummary}`;
+        const anyFailed = result.written.some(w => !w.ok);
+
+        return [{
+            status: anyFailed ? '⚠ partial' : '✅ saved',
+            clip: clip.id.slice(0, 8),
+            title: clip.title || '(untitled)',
+            files: `📁 ${fileSummary}`,
+            link: `🔗 ${link}`,
+        }];
+    },
+});

package/clis/suno/download.test.js

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    ensureSunoSession: vi.fn(),
+    downloadSunoClip: vi.fn(),
+}));
+
+vi.mock('./utils.js', () => ({
+    STUDIO_API: 'https://studio-api-prod.suno.com',
+    SUNO_DOMAIN: 'suno.com',
+    SUNO_URL: 'https://suno.com',
+    ensureSunoSession: mocks.ensureSunoSession,
+    downloadSunoClip: mocks.downloadSunoClip,
+    normalizeBooleanFlag: (value, fallback = false) => {
+        if (typeof value === 'boolean') return value;
+        if (value == null || value === '') return fallback;
+        const s = String(value).trim().toLowerCase();
+        return s === 'true' || s === '1' || s === 'yes' || s === 'on';
+    },
+    parseFormats: (value) => {
+        if (!value) return ['mp3', 'metadata'];
+        return String(value).split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    },
+    resolveSunoOutputDir: (value) => value || '/tmp/suno-test',
+    unwrapEvaluateResult: (value) => value && typeof value === 'object' && 'session' in value && 'data' in value ? value.data : value,
+}));
+
+const { downloadCommand } = await import('./download.js');
+
+const okSession = { ok: true, deviceId: 'device-uuid' };
+const okCompleteClip = { id: '11111111-2222-3333-4444-555555555555', status: 'complete', title: 'Probe', audio_url: 'https://cdn1.suno.ai/x.mp3' };
+
+function createPageWithFeed(clips) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue({ ok: true, clips }),
+    };
+}
+
+beforeEach(() => {
+    vi.restoreAllMocks();
+    mocks.ensureSunoSession.mockReset().mockResolvedValue(okSession);
+    mocks.downloadSunoClip.mockReset().mockResolvedValue({
+        slug: 'probe',
+        written: [{ format: 'mp3', file: '/tmp/probe.mp3', ok: true }, { format: 'metadata', file: '/tmp/probe.json', ok: true }],
+    });
+});
+
+describe('suno download argument validation', () => {
+    it('parses bare UUID clip ids', async () => {
+        const id = okCompleteClip.id;
+        await downloadCommand.func(createPageWithFeed([okCompleteClip]), { clip: id, formats: 'mp3' });
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), okCompleteClip, '/tmp/suno-test', ['mp3'], 'device-uuid');
+    });
+
+    it('extracts UUID from a full suno.com/song/<id> URL', async () => {
+        const id = okCompleteClip.id;
+        await downloadCommand.func(createPageWithFeed([okCompleteClip]), { clip: `https://suno.com/song/${id}`, formats: 'mp3' });
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), okCompleteClip, '/tmp/suno-test', ['mp3'], 'device-uuid');
+    });
+
+    it('rejects off-domain URLs even if they contain a UUID', async () => {
+        const id = okCompleteClip.id;
+        await expect(downloadCommand.func(createPageWithFeed([]), { clip: `https://evil.example/song/${id}`, formats: 'mp3' })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('Invalid clip-id'),
+        });
+    });
+
+    it('rejects non-UUID clip ids with ArgumentError', async () => {
+        await expect(downloadCommand.func(createPageWithFeed([]), { clip: 'not-a-uuid', formats: 'mp3' })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('Invalid clip-id'),
+        });
+    });
+});
+
+describe('suno download lookup and status handling', () => {
+    it('returns EmptyResultError when feed/v3 does not contain the clip', async () => {
+        await expect(downloadCommand.func(createPageWithFeed([]), { clip: okCompleteClip.id, formats: 'mp3' })).rejects.toMatchObject({
+            code: 'EMPTY_RESULT',
+            hint: expect.stringContaining('not found'),
+        });
+    });
+
+    it('unwraps Browser Bridge envelopes around feed lookup results', async () => {
+        const page = createPageWithFeed([]);
+        page.evaluate.mockResolvedValueOnce({ session: 'browser:default', data: { ok: true, clips: [okCompleteClip] } });
+        await downloadCommand.func(page, { clip: okCompleteClip.id, formats: 'mp3' });
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), okCompleteClip, '/tmp/suno-test', ['mp3'], 'device-uuid');
+    });
+
+    it('fails typed when feed/v3 returns malformed clips payload', async () => {
+        const page = createPageWithFeed([]);
+        page.evaluate.mockResolvedValueOnce({ ok: true, clips: null });
+        await expect(downloadCommand.func(page, { clip: okCompleteClip.id, formats: 'mp3' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed clips payload'),
+        });
+    });
+
+    it('refuses to download when the clip is still streaming/queued', async () => {
+        await expect(downloadCommand.func(createPageWithFeed([{ ...okCompleteClip, status: 'streaming' }]), { clip: okCompleteClip.id, formats: 'mp3' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('not complete yet'),
+        });
+    });
+});
+
+describe('suno download paid-format guard', () => {
+    it('skips wav by default and surfaces the skip in the result row', async () => {
+        const out = await downloadCommand.func(createPageWithFeed([okCompleteClip]), {
+            clip: okCompleteClip.id,
+            formats: 'mp3,wav,metadata',
+        });
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), okCompleteClip, '/tmp/suno-test', ['mp3', 'metadata'], 'device-uuid');
+        expect(out[0].files).toContain('skipped(needs --confirm-paid):wav');
+    });
+
+    it('rejects requests where every requested format is paid and unconfirmed', async () => {
+        await expect(downloadCommand.func(createPageWithFeed([okCompleteClip]), {
+            clip: okCompleteClip.id,
+            formats: 'wav',
+        })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('All requested formats require'),
+        });
+        expect(mocks.downloadSunoClip).not.toHaveBeenCalled();
+    });
+
+    it('includes wav when --confirm-paid is true', async () => {
+        await downloadCommand.func(createPageWithFeed([okCompleteClip]), {
+            clip: okCompleteClip.id,
+            formats: 'mp3,wav',
+            'confirm-paid': true,
+        });
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), okCompleteClip, '/tmp/suno-test', ['mp3', 'wav'], 'device-uuid');
+    });
+
+    it('fails typed when selected formats write no files', async () => {
+        mocks.downloadSunoClip.mockResolvedValue({ slug: 'probe', written: [{ format: 'mp3', file: null, ok: false, reason: 'HTTP 500' }] });
+        await expect(downloadCommand.func(createPageWithFeed([okCompleteClip]), {
+            clip: okCompleteClip.id,
+            formats: 'mp3',
+        })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('wrote no files'),
+        });
+    });
+});