@jackwener/opencli 1.7.22 → 1.8.1

package/clis/suno/utils.test.js

@@ -0,0 +1,329 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import {
+    DEFAULT_FORMATS,
+    SUPPORTED_FORMATS,
+    SUNO_MODELS,
+    clampSlider,
+    normalizeBooleanFlag,
+    requireNonNegativeInt,
+    parseFormats,
+    requirePositiveInt,
+    resolveSunoOutputDir,
+    sanitizeTitleForFilename,
+    unwrapEvaluateResult,
+    pollSunoClips,
+    ensureSunoSession,
+    parseSunoBillingInfo,
+} from './utils.js';
+
+describe('suno utils — parseFormats', () => {
+    it('returns the default format set when input is empty or missing', () => {
+        expect(parseFormats(undefined)).toEqual(DEFAULT_FORMATS);
+        expect(parseFormats(null)).toEqual(DEFAULT_FORMATS);
+        expect(parseFormats('')).toEqual(DEFAULT_FORMATS);
+        expect(parseFormats('   ')).toEqual(DEFAULT_FORMATS);
+    });
+
+    it('parses comma-separated input and trims whitespace', () => {
+        expect(parseFormats('mp3, wav, metadata')).toEqual(['mp3', 'wav', 'metadata']);
+    });
+
+    it('lowercases and deduplicates input', () => {
+        expect(parseFormats('MP3,Mp3,mp3,WAV')).toEqual(['mp3', 'wav']);
+    });
+
+    it('accepts array inputs (e.g. when caller passes pre-split values)', () => {
+        expect(parseFormats(['mp3', 'metadata'])).toEqual(['mp3', 'metadata']);
+    });
+
+    it('throws ArgumentError on unsupported format and lists the supported set', () => {
+        try {
+            parseFormats('mp3,flac');
+            throw new Error('should have thrown');
+        } catch (err) {
+            expect(err).toBeInstanceOf(ArgumentError);
+            expect(err.message).toContain('flac');
+            expect(err.hint).toContain(SUPPORTED_FORMATS.join(', '));
+        }
+    });
+});
+
+describe('suno utils — resolveSunoOutputDir', () => {
+    it('falls back to ~/Music/suno when no path is given', () => {
+        expect(resolveSunoOutputDir()).toBe(path.join(os.homedir(), 'Music', 'suno'));
+        expect(resolveSunoOutputDir('')).toBe(path.join(os.homedir(), 'Music', 'suno'));
+    });
+
+    it('expands ~ and ~/-prefixed relative paths to the home directory', () => {
+        expect(resolveSunoOutputDir('~')).toBe(os.homedir());
+        expect(resolveSunoOutputDir('~/Music/test')).toBe(path.join(os.homedir(), 'Music', 'test'));
+    });
+
+    it('absolute paths are returned as-is (resolved)', () => {
+        expect(resolveSunoOutputDir('/tmp/suno')).toBe('/tmp/suno');
+    });
+});
+
+describe('suno utils — sanitizeTitleForFilename', () => {
+    it('replaces filesystem-hostile characters with hyphens', () => {
+        expect(sanitizeTitleForFilename('foo/bar:baz?')).toBe('foo-bar-baz-');
+    });
+
+    it('collapses whitespace and trims', () => {
+        expect(sanitizeTitleForFilename('  hello   world  ')).toBe('hello world');
+    });
+
+    it('caps length at 60 characters', () => {
+        const long = 'a'.repeat(120);
+        expect(sanitizeTitleForFilename(long).length).toBe(60);
+    });
+
+    it('returns fallback for empty input', () => {
+        expect(sanitizeTitleForFilename('', 'untitled')).toBe('untitled');
+        expect(sanitizeTitleForFilename(null, 'fallback')).toBe('fallback');
+    });
+});
+
+describe('suno utils — clampSlider', () => {
+    it('returns the default when input is missing', () => {
+        expect(clampSlider(undefined, '--weirdness', 0.5)).toBe(0.5);
+        expect(clampSlider('', '--weirdness', 0.5)).toBe(0.5);
+        expect(clampSlider(null, '--weirdness', 0.5)).toBe(0.5);
+    });
+
+    it('parses numeric strings and accepts 0..1', () => {
+        expect(clampSlider('0', '--x', 0.5)).toBe(0);
+        expect(clampSlider('0.74', '--x', 0.5)).toBe(0.74);
+        expect(clampSlider('1', '--x', 0.5)).toBe(1);
+    });
+
+    it('rejects out-of-range or non-numeric values', () => {
+        expect(() => clampSlider('1.5', '--x', 0.5)).toThrowError(ArgumentError);
+        expect(() => clampSlider('-0.1', '--x', 0.5)).toThrowError(ArgumentError);
+        expect(() => clampSlider('hello', '--x', 0.5)).toThrowError(ArgumentError);
+    });
+});
+
+describe('suno utils — normalizeBooleanFlag', () => {
+    it('treats the canonical true-ish strings as true', () => {
+        for (const v of ['true', '1', 'yes', 'on', 'TRUE', 'On']) {
+            expect(normalizeBooleanFlag(v)).toBe(true);
+        }
+    });
+
+    it('treats unset / empty / unrecognized values as the fallback', () => {
+        expect(normalizeBooleanFlag(undefined)).toBe(false);
+        expect(normalizeBooleanFlag('', true)).toBe(true);
+        expect(normalizeBooleanFlag('maybe')).toBe(false);
+    });
+
+    it('passes through actual booleans', () => {
+        expect(normalizeBooleanFlag(true)).toBe(true);
+        expect(normalizeBooleanFlag(false)).toBe(false);
+    });
+});
+
+describe('suno utils — requirePositiveInt', () => {
+    it('returns positive integers as numbers', () => {
+        expect(requirePositiveInt(5, '--limit')).toBe(5);
+        expect(requirePositiveInt('10', '--limit')).toBe(10);
+    });
+
+    it('rejects zero, negative, and non-integer values', () => {
+        expect(() => requirePositiveInt(0, '--limit')).toThrowError(ArgumentError);
+        expect(() => requirePositiveInt(-3, '--limit')).toThrowError(ArgumentError);
+        expect(() => requirePositiveInt(1.5, '--limit')).toThrowError(ArgumentError);
+        expect(() => requirePositiveInt('not a number', '--limit')).toThrowError(ArgumentError);
+    });
+});
+
+describe('suno utils — requireNonNegativeInt', () => {
+    it('returns zero and positive integers as numbers', () => {
+        expect(requireNonNegativeInt(0, '--page')).toBe(0);
+        expect(requireNonNegativeInt('3', '--page')).toBe(3);
+    });
+
+    it('rejects negative or non-integer values', () => {
+        expect(() => requireNonNegativeInt(-1, '--page')).toThrowError(ArgumentError);
+        expect(() => requireNonNegativeInt(1.5, '--page')).toThrowError(ArgumentError);
+        expect(() => requireNonNegativeInt('nope', '--page')).toThrowError(ArgumentError);
+    });
+});
+
+describe('suno utils — unwrapEvaluateResult', () => {
+    it('unwraps Browser Bridge envelopes at evaluate boundaries', () => {
+        const payload = { ok: true, clips: [] };
+        expect(unwrapEvaluateResult({ session: 'browser:default', data: payload })).toBe(payload);
+        expect(unwrapEvaluateResult(payload)).toBe(payload);
+    });
+});
+
+describe('suno utils — parseSunoBillingInfo', () => {
+    it('resolves the free-tier plan when subscription_type is false (#1704)', () => {
+        const parsed = parseSunoBillingInfo({
+            subscription_type: false,
+            credits: 0,
+            monthly_limit: 50,
+            monthly_usage: 10,
+            total_credits_left: 40,
+            credit_packs: [],
+            plans: [
+                { id: '4497580c-f4eb-4f86-9f0e-960eb7c48d7d', name: 'Free Plan', plan_key: 'free', level: 0 },
+                { id: '3eaebef3-ef46-446a-931c-3d50cd1514f1', name: 'Pro Plan', plan_key: 'pro', level: 10 },
+            ],
+        });
+        expect(parsed.planId).toBe('4497580c-f4eb-4f86-9f0e-960eb7c48d7d');
+        expect(parsed.planKey).toBe('free');
+        expect(parsed.totalCreditsAvailable).toBe(40);
+        expect(parsed.breakdown.monthlyRemaining).toBe(40);
+        expect(parsed.breakdown.monthlyLimit).toBe(50);
+    });
+
+    it('resolves the paid-tier plan when subscription_type matches a plan_key', () => {
+        const parsed = parseSunoBillingInfo({
+            subscription_type: 'pro',
+            credits: 0,
+            monthly_limit: 2500,
+            monthly_usage: 100,
+            total_credits_left: 2400,
+            credit_packs: [{ id: 'pack-1', amount: 500 }],
+            plans: [
+                { id: 'free-uuid', name: 'Free Plan', plan_key: 'free', level: 0 },
+                { id: 'pro-uuid', name: 'Pro Plan', plan_key: 'pro', level: 10 },
+            ],
+        });
+        expect(parsed.planId).toBe('pro-uuid');
+        expect(parsed.planKey).toBe('pro');
+        expect(parsed.totalCreditsAvailable).toBe(2400);
+    });
+
+    it('falls back to subscription_type as planKey when plans[] lookup misses', () => {
+        const parsed = parseSunoBillingInfo({
+            subscription_type: 'enterprise',
+            plans: [{ plan_key: 'pro' }, { plan_key: 'premier' }],
+        });
+        expect(parsed.planId).toBeNull();
+        expect(parsed.planKey).toBe('enterprise');
+    });
+
+    it('returns planId null when plans[] is missing and there is no legacy plan field', () => {
+        const parsed = parseSunoBillingInfo({ subscription_type: false });
+        expect(parsed.planId).toBeNull();
+        expect(parsed.planKey).toBe('free');
+    });
+
+    it('honours the legacy data.plan field when plans[] does not surface a match', () => {
+        const parsed = parseSunoBillingInfo({
+            subscription_type: false,
+            plan: { id: 'legacy-uuid', plan_key: 'legacy' },
+        });
+        expect(parsed.planId).toBe('legacy-uuid');
+        expect(parsed.planKey).toBe('legacy');
+    });
+
+    it('sums credit_packs by amount and falls back to legacy credits field', () => {
+        const parsed = parseSunoBillingInfo({
+            subscription_type: false,
+            credits: 5,
+            monthly_limit: 0,
+            monthly_usage: 0,
+            credit_packs: [{ amount: 100 }, { credits: 50 }],
+            plans: [{ plan_key: 'free' }],
+        });
+        expect(parsed.breakdown.pack).toBe(5);
+        expect(parsed.breakdown.purchasedPacks).toBe(150);
+        expect(parsed.totalCreditsAvailable).toBe(155);
+    });
+});
+
+describe('suno utils — ensureSunoSession typed failures', () => {
+    function createSessionPage(sessionCheckResult) {
+        const evaluate = async (script) => {
+            if (script.includes('querySelectorAll')) return undefined;
+            if (script.includes('!!(window.Clerk && window.Clerk.session)')) return true;
+            if (script.includes('suno_device_id')) return 'device-id';
+            if (script.includes('/api/billing/info/')) return sessionCheckResult;
+            throw new Error(`unexpected evaluate script: ${script.slice(0, 80)}`);
+        };
+        return {
+            goto: async () => undefined,
+            wait: async () => undefined,
+            evaluate,
+        };
+    }
+
+    it('maps explicit logged-out session state to AuthRequiredError', async () => {
+        await expect(ensureSunoSession(createSessionPage({
+            ok: false,
+            auth: true,
+            error: 'Clerk session unavailable',
+        }))).rejects.toThrowError(AuthRequiredError);
+    });
+
+    it('does not classify billing/parser drift as logged out', async () => {
+        await expect(ensureSunoSession(createSessionPage({
+            ok: false,
+            error: 'Malformed billing/info JSON: Unexpected token <',
+        }))).rejects.toThrowError(CommandExecutionError);
+    });
+
+    it('resolves a free-tier session without throwing when subscription_type is false (#1704)', async () => {
+        const session = await ensureSunoSession(createSessionPage({
+            ok: true,
+            planId: '4497580c-f4eb-4f86-9f0e-960eb7c48d7d',
+            planKey: 'free',
+            planName: 'Free Plan',
+            totalCreditsAvailable: 40,
+            breakdown: { pack: 0, purchasedPacks: 0, monthlyRemaining: 40, monthlyLimit: 50, monthlyUsed: 10 },
+        }));
+        expect(session.planKey).toBe('free');
+        expect(session.planId).toBe('4497580c-f4eb-4f86-9f0e-960eb7c48d7d');
+        expect(session.totalCreditsAvailable).toBe(40);
+    });
+
+    it('still resolves when planId is null so read commands work even on unparseable plan shapes', async () => {
+        const session = await ensureSunoSession(createSessionPage({
+            ok: true,
+            planId: null,
+            planKey: 'free',
+            planName: null,
+            totalCreditsAvailable: 0,
+            breakdown: { pack: 0, purchasedPacks: 0, monthlyRemaining: 0, monthlyLimit: 0, monthlyUsed: 0 },
+        }));
+        expect(session.planId).toBeNull();
+        expect(session.planKey).toBe('free');
+    });
+});
+
+describe('suno utils — model + format exports', () => {
+    it('exposes the four shipping models with chirp-fenix first', () => {
+        expect(SUNO_MODELS).toContain('chirp-fenix');
+        expect(SUNO_MODELS).toContain('chirp-bluejay');
+        expect(SUNO_MODELS[0]).toBe('chirp-fenix');
+    });
+
+    it('declares mp3 + metadata as the default download set', () => {
+        expect(DEFAULT_FORMATS).toEqual(['mp3', 'metadata']);
+    });
+});
+
+describe('suno utils — pollSunoClips', () => {
+    it('fails typed on malformed feed JSON while polling generation status', async () => {
+        const page = {
+            evaluate: async () => ({ status: 200, body: null }),
+            wait: async () => {},
+        };
+        await expect(pollSunoClips(page, ['clip-a'], 1, 'device-id', 0)).rejects.toThrowError(CommandExecutionError);
+    });
+
+    it('fails typed on non-auth HTTP feed failures while polling generation status', async () => {
+        const page = {
+            evaluate: async () => ({ status: 500, body: { clips: [] } }),
+            wait: async () => {},
+        };
+        await expect(pollSunoClips(page, ['clip-a'], 1, 'device-id', 0)).rejects.toThrowError(CommandExecutionError);
+    });
+});

package/clis/twitter/device-follow.js

@@ -0,0 +1,193 @@
+/**
+ * Twitter `/i/timeline` device-follow notification stream, i.e. the
+ * curated tweet list aggregated under a bell-icon "new posts from
+ * @userA and N others" notification. Direct GET /i/timeline redirects
+ * to /home; the data is only reachable via the legacy v1.1 REST
+ * endpoint `/i/api/2/notifications/device_follow.json`.
+ *
+ * Endpoint discovery and field-mapping originally proposed by @traddo
+ * in issue #1628.
+ */
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
+
+const DEVICE_FOLLOW_PATH = '/i/api/2/notifications/device_follow.json';
+const MAX_LIMIT = 200;
+
+function parseLimit(value) {
+    if (value === undefined || value === null || value === '') return 20;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be an integer between 1 and ${MAX_LIMIT}`);
+    }
+    return limit;
+}
+
+function buildDeviceFollowUrl(count) {
+    const params = new URLSearchParams({
+        include_profile_interstitial_type: '1',
+        include_blocking: '1',
+        include_blocked_by: '1',
+        include_followed_by: '1',
+        include_want_retweets: '1',
+        include_mute_edge: '1',
+        include_can_dm: '1',
+        include_can_media_tag: '1',
+        include_ext_has_nft_avatar: '1',
+        include_ext_is_blue_verified: '1',
+        include_ext_verified_type: '1',
+        skip_status: '1',
+        cards_platform: 'Web-12',
+        include_cards: '1',
+        include_ext_alt_text: 'true',
+        include_quote_count: 'true',
+        include_reply_count: '1',
+        tweet_mode: 'extended',
+        include_ext_views: 'true',
+        count: String(count),
+    });
+    return `${DEVICE_FOLLOW_PATH}?${params.toString()}`;
+}
+
+function extractEntries(timeline) {
+    if (!timeline || !Array.isArray(timeline.instructions)) return null;
+    const out = [];
+    for (const inst of timeline.instructions) {
+        const entries = inst?.addEntries?.entries;
+        if (Array.isArray(entries)) out.push(...entries);
+    }
+    return out;
+}
+
+function joinEntryToTweet(entry, tweets, users) {
+    const tweetId = entry?.content?.item?.content?.tweet?.id;
+    if (!tweetId) return null;
+    const tw = tweets?.[tweetId];
+    if (!tw) return null;
+    const user = users?.[tw.user_id_str] || null;
+    if (typeof user?.screen_name !== 'string' || !user.screen_name) return null;
+    return { tweetId, tweet: tw, user };
+}
+
+function shapeRow({ tweetId, tweet, user }) {
+    const screenName = user.screen_name;
+    return {
+        id: tweetId,
+        author: screenName,
+        text: tweet?.full_text || tweet?.text || '',
+        likes: tweet?.favorite_count ?? 0,
+        retweets: tweet?.retweet_count ?? 0,
+        replies: tweet?.reply_count ?? 0,
+        // The legacy v1.1 endpoint does not return view counts even with
+        // include_ext_views=true; surface null rather than a 0 sentinel
+        // that would lie about real engagement (typed-errors §3).
+        views: null,
+        created_at: tweet?.created_at || '',
+        url: `https://x.com/${screenName}/status/${tweetId}`,
+    };
+}
+
+function parseDeviceFollow(payload, seen) {
+    if (!payload?.globalObjects || typeof payload.globalObjects !== 'object') return null;
+    const tweets = payload?.globalObjects?.tweets || {};
+    const users = payload?.globalObjects?.users || {};
+    if (typeof tweets !== 'object' || typeof users !== 'object') return null;
+    const entries = extractEntries(payload?.timeline);
+    if (!entries) return null;
+    const rows = [];
+    let unmatchedTweetEntries = 0;
+    let malformedEntries = 0;
+    for (const entry of entries) {
+        const hasTweetEntry = Boolean(entry?.content?.item?.content?.tweet?.id);
+        if (!hasTweetEntry) {
+            malformedEntries++;
+            continue;
+        }
+        const joined = joinEntryToTweet(entry, tweets, users);
+        if (!joined) {
+            unmatchedTweetEntries++;
+            continue;
+        }
+        if (seen.has(joined.tweetId)) continue;
+        seen.add(joined.tweetId);
+        rows.push(shapeRow(joined));
+    }
+    return { rows, entryCount: entries.length, unmatchedTweetEntries, malformedEntries };
+}
+
+cli({
+    site: 'twitter',
+    name: 'device-follow',
+    access: 'read',
+    description: 'Read the /i/timeline device-follow notification stream (tweets aggregated under a bell-icon "new posts from @userA and N others" notification)',
+    domain: 'x.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: `Maximum number of tweets to return (1-${MAX_LIMIT}, default 20)` },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank by weighted engagement and return the top N. Default 0 keeps upstream ordering.' },
+    ],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url'],
+    func: async (page, kwargs) => {
+        const limit = parseLimit(kwargs.limit);
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
+        if (!ct0) throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
+
+        const apiUrl = buildDeviceFollowUrl(limit);
+        const headers = JSON.stringify({
+            Authorization: `Bearer ${decodeURIComponent(TWITTER_BEARER_TOKEN)}`,
+            'X-Csrf-Token': ct0,
+            'X-Twitter-Auth-Type': 'OAuth2Session',
+            'X-Twitter-Active-User': 'yes',
+        });
+        const data = await page.evaluate(`async () => {
+        try {
+          const r = await fetch("${apiUrl}", { method: "GET", headers: ${headers}, credentials: 'include' });
+          if (!r.ok) return { error: r.status };
+          try {
+            return await r.json();
+          } catch (e) {
+            return { errorKind: 'non_json', detail: String(e && e.message || e) };
+          }
+        } catch (e) {
+          return { errorKind: 'exception', detail: String(e && e.message || e) };
+        }
+      }`);
+        if (data?.errorKind === 'non_json') {
+            throw new CommandExecutionError(`Twitter device-follow returned non-JSON response: ${data.detail || 'unknown parse error'}`);
+        }
+        if (data?.errorKind === 'exception') {
+            throw new CommandExecutionError(`Twitter device-follow fetch failed: ${data.detail || 'unknown error'}`);
+        }
+        if (data?.error) {
+            if (data.error === 401 || data.error === 403) {
+                throw new AuthRequiredError('x.com', `Twitter device-follow returned HTTP ${data.error}`);
+            }
+            throw new CommandExecutionError(`HTTP ${data.error}: Failed to fetch device-follow notification stream.`);
+        }
+        const parsed = parseDeviceFollow(data, new Set());
+        if (!parsed) {
+            throw new CommandExecutionError('Twitter device-follow response was missing the expected timeline/globalObjects shape.');
+        }
+        if (parsed.malformedEntries > 0 || parsed.unmatchedTweetEntries > 0) {
+            throw new CommandExecutionError('Twitter device-follow entries could not be joined to tweet/user objects.');
+        }
+        if (parsed.rows.length === 0) {
+            throw new EmptyResultError('twitter device-follow', 'No device-follow notification tweets found.');
+        }
+        const rows = parsed.rows;
+        const trimmed = rows.slice(0, limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
+    },
+});
+
+export const __test__ = {
+    buildDeviceFollowUrl,
+    extractEntries,
+    joinEntryToTweet,
+    shapeRow,
+    parseDeviceFollow,
+    parseLimit,
+};