@jackwener/opencli 1.8.0 → 1.8.1

package/clis/pixiv/detail.test.js

@@ -0,0 +1,93 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { createPageMock } from '../test-utils.js';
+import './detail.js';
+let cmd;
+beforeAll(() => {
+    cmd = getRegistry().get('pixiv/detail');
+    expect(cmd?.func).toBeTypeOf('function');
+});
+describe('pixiv detail', () => {
+    it('throws ArgumentError on invalid illustration ID before navigation', async () => {
+        const page = createPageMock([]);
+        await expect(cmd.func(page, { id: 'xyz' })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+    it('throws AuthRequiredError on 401', async () => {
+        const page = createPageMock([{ __httpError: 401 }]);
+        await expect(cmd.func(page, { id: '12345' })).rejects.toThrow(AuthRequiredError);
+    });
+    it('throws CommandExecutionError on 404', async () => {
+        const page = createPageMock([{ __httpError: 404 }]);
+        await expect(cmd.func(page, { id: '12345' })).rejects.toThrow(CommandExecutionError);
+    });
+    it('throws CommandExecutionError on non-auth HTTP failure', async () => {
+        const page = createPageMock([{ __httpError: 500 }]);
+        await expect(cmd.func(page, { id: '12345' })).rejects.toThrow(CommandExecutionError);
+    });
+    it('surfaces HTTP error body messages from pixivFetch', async () => {
+        const page = createPageMock([{ __httpError: 429, message: 'Too many requests' }]);
+        await expect(cmd.func(page, { id: '12345' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('Too many requests'),
+        });
+    });
+    it('fails typed when the detail body lacks stable illustration identity fields', async () => {
+        const page = createPageMock([{ body: { illustId: '12345', illustTitle: 'Title' } }]);
+        await expect(cmd.func(page, { id: '12345' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed detail payload'),
+        });
+    });
+    it('fails typed when the detail body id does not match the requested illustration', async () => {
+        const page = createPageMock([
+            {
+                body: {
+                    illustId: '99999',
+                    illustTitle: 'Wrong',
+                    userName: 'Artist',
+                    userId: '99',
+                },
+            },
+        ]);
+        await expect(cmd.func(page, { id: '12345' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed detail payload'),
+        });
+    });
+    it('returns detail row with mapped fields', async () => {
+        const page = createPageMock([
+            {
+                body: {
+                    illustId: '12345',
+                    illustTitle: 'Test Illust',
+                    userName: 'Test Artist',
+                    userId: '99',
+                    illustType: 1,
+                    pageCount: 4,
+                    bookmarkCount: 200,
+                    likeCount: 100,
+                    viewCount: 5000,
+                    tags: { tags: [{ tag: 'original' }, { tag: 'fantasy' }] },
+                    createDate: '2025-01-15T12:00:00+09:00',
+                },
+            },
+        ]);
+        const result = await cmd.func(page, { id: '12345' });
+        expect(result).toEqual([{
+            illust_id: '12345',
+            title: 'Test Illust',
+            author: 'Test Artist',
+            user_id: '99',
+            type: 'manga',
+            pages: 4,
+            bookmarks: 200,
+            likes: 100,
+            views: 5000,
+            tags: 'original, fantasy',
+            created: '2025-01-15',
+            url: 'https://www.pixiv.net/artworks/12345',
+        }]);
+    });
+});

package/clis/pixiv/user.js

@@ -1,4 +1,18 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { pixivFetch } from './utils.js';
+
+function requireUserBody(body, uid) {
+    if (!body || Array.isArray(body) || typeof body !== 'object') {
+        throw new CommandExecutionError(`Pixiv user ${uid} returned malformed profile payload`);
+    }
+    const name = String(body.name ?? '').trim();
+    if (!name) {
+        throw new CommandExecutionError(`Pixiv user ${uid} returned malformed profile payload`);
+    }
+    return { ...body, name };
+}
+
 cli({
     site: 'pixiv',
     name: 'user',
@@ -6,7 +20,6 @@ cli({
     description: 'View Pixiv artist profile',
     domain: 'www.pixiv.net',
     strategy: Strategy.COOKIE,
-    browser: true,
     args: [
         { name: 'uid', required: true, positional: true, help: 'Pixiv user ID' },
     ],
@@ -21,34 +34,26 @@ cli({
         'comment',
         'url',
     ],
-    pipeline: [
-        { navigate: 'https://www.pixiv.net' },
-        { evaluate: `(async () => {
-  const uid = \${{ args.uid | json }};
-  const res = await fetch(
-    'https://www.pixiv.net/ajax/user/' + uid + '?full=1',
-    { credentials: 'include' }
-  );
-  if (!res.ok) {
-    if (res.status === 401 || res.status === 403) throw new Error('Authentication required — please log in to Pixiv in Chrome');
-    if (res.status === 404) throw new Error('User not found: ' + uid);
-    throw new Error('Pixiv request failed (HTTP ' + res.status + ')');
-  }
-  const data = await res.json();
-  const b = data?.body;
-  if (!b) throw new Error('User not found');
-  return [{
-    user_id: uid,
-    name: b.name,
-    premium: b.premium ? 'Yes' : 'No',
-    following: b.following,
-    illusts: typeof b.illusts === 'object' ? Object.keys(b.illusts).length : (b.illusts || 0),
-    manga: typeof b.manga === 'object' ? Object.keys(b.manga).length : (b.manga || 0),
-    novels: typeof b.novels === 'object' ? Object.keys(b.novels).length : (b.novels || 0),
-    comment: (b.comment || '').slice(0, 80),
-    url: 'https://www.pixiv.net/users/' + uid
-  }];
-})()
-` },
-    ],
+    func: async (page, kwargs) => {
+        const uid = String(kwargs.uid ?? '');
+        if (!/^\d+$/.test(uid)) {
+            throw new ArgumentError(`Invalid user ID: ${uid}`, 'Example: opencli pixiv user 123456');
+        }
+        const body = await pixivFetch(page, `/ajax/user/${uid}`, {
+            params: { full: 1 },
+            notFoundMsg: `User not found: ${uid}`,
+        });
+        const b = requireUserBody(body, uid);
+        return [{
+            user_id: uid,
+            name: b.name,
+            premium: b.premium ? 'Yes' : 'No',
+            following: b.following,
+            illusts: typeof b.illusts === 'object' ? Object.keys(b.illusts).length : (b.illusts || 0),
+            manga: typeof b.manga === 'object' ? Object.keys(b.manga).length : (b.manga || 0),
+            novels: typeof b.novels === 'object' ? Object.keys(b.novels).length : (b.novels || 0),
+            comment: (b.comment || '').slice(0, 80),
+            url: `https://www.pixiv.net/users/${uid}`,
+        }];
+    },
 });

package/clis/pixiv/user.test.js

@@ -0,0 +1,100 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { createPageMock } from '../test-utils.js';
+import './user.js';
+let cmd;
+beforeAll(() => {
+    cmd = getRegistry().get('pixiv/user');
+    expect(cmd?.func).toBeTypeOf('function');
+});
+describe('pixiv user', () => {
+    it('throws ArgumentError on invalid user ID before navigation', async () => {
+        const page = createPageMock([]);
+        await expect(cmd.func(page, { uid: 'abc' })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+    it('throws AuthRequiredError on 401', async () => {
+        const page = createPageMock([{ __httpError: 401 }]);
+        await expect(cmd.func(page, { uid: '11' })).rejects.toThrow(AuthRequiredError);
+    });
+    it('throws CommandExecutionError on 404', async () => {
+        const page = createPageMock([{ __httpError: 404 }]);
+        await expect(cmd.func(page, { uid: '11' })).rejects.toThrow(CommandExecutionError);
+    });
+    it('throws CommandExecutionError on non-auth HTTP failure', async () => {
+        const page = createPageMock([{ __httpError: 500 }]);
+        await expect(cmd.func(page, { uid: '11' })).rejects.toThrow(CommandExecutionError);
+    });
+    it('unwraps Browser Bridge envelopes around Pixiv API payloads', async () => {
+        const page = createPageMock([
+            {
+                session: 'site:pixiv',
+                data: {
+                    body: {
+                        name: 'Envelope Artist',
+                        premium: false,
+                        following: 0,
+                        illusts: {},
+                        manga: {},
+                        novels: {},
+                    },
+                },
+            },
+        ]);
+        const result = await cmd.func(page, { uid: '12' });
+        expect(result[0]).toMatchObject({
+            user_id: '12',
+            name: 'Envelope Artist',
+            premium: 'No',
+        });
+    });
+    it('surfaces Pixiv API error bodies instead of treating them as not found', async () => {
+        const page = createPageMock([{ error: true, message: 'rate limited' }]);
+        await expect(cmd.func(page, { uid: '11' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: 'rate limited',
+        });
+    });
+    it('fails typed on malformed Pixiv API payloads', async () => {
+        const page = createPageMock([{ ok: true }]);
+        await expect(cmd.func(page, { uid: '11' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed API payload'),
+        });
+    });
+    it('fails typed when the user body lacks stable profile identity fields', async () => {
+        const page = createPageMock([{ body: { premium: false, following: 0 } }]);
+        await expect(cmd.func(page, { uid: '11' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed profile payload'),
+        });
+    });
+    it('returns profile row with computed counts for object-shaped illust fields', async () => {
+        const page = createPageMock([
+            {
+                body: {
+                    name: 'Test Artist',
+                    premium: true,
+                    following: 42,
+                    illusts: { '111': null, '222': null, '333': null },
+                    manga: {},
+                    novels: { '999': null },
+                    comment: 'Hello world',
+                },
+            },
+        ]);
+        const result = await cmd.func(page, { uid: '11' });
+        expect(result).toEqual([{
+            user_id: '11',
+            name: 'Test Artist',
+            premium: 'Yes',
+            following: 42,
+            illusts: 3,
+            manga: 0,
+            novels: 1,
+            comment: 'Hello world',
+            url: 'https://www.pixiv.net/users/11',
+        }]);
+    });
+});

package/clis/pixiv/utils.js

@@ -7,6 +7,25 @@
  */
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 const PIXIV_DOMAIN = 'www.pixiv.net';
+
+function unwrapEvaluateResult(payload) {
+    if (payload && !Array.isArray(payload) && typeof payload === 'object' && 'session' in payload && 'data' in payload) {
+        return payload.data;
+    }
+    return payload;
+}
+
+function extractPixivErrorMessage(payload) {
+    if (!payload || typeof payload !== 'object') return '';
+    const candidates = [
+        payload.message,
+        payload.errorMessage,
+        payload.error?.message,
+        payload.error,
+    ];
+    const found = candidates.find((value) => typeof value === 'string' && value.trim());
+    return found ? found.trim() : '';
+}
 /**
  * Navigate to Pixiv (to attach cookies) then fetch a Pixiv Ajax API endpoint.
  *
@@ -21,27 +40,57 @@ const PIXIV_DOMAIN = 'www.pixiv.net';
  * @throws CommandExecutionError on 404 or other HTTP errors
  */
 export async function pixivFetch(page, path, opts = {}) {
-    await page.goto(`https://${PIXIV_DOMAIN}`);
+    try {
+        await page.goto(`https://${PIXIV_DOMAIN}`);
+    } catch (error) {
+        throw new CommandExecutionError(`Pixiv navigation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const qs = opts.params
         ? '?' + Object.entries(opts.params).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')
         : '';
     const url = `https://${PIXIV_DOMAIN}${path}${qs}`;
-    const data = await page.evaluate(`
+    let data;
+    try {
+        data = unwrapEvaluateResult(await page.evaluate(`
     (async () => {
       const res = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
-      if (!res.ok) return { __httpError: res.status };
-      return await res.json();
+      const text = await res.text();
+      let json = null;
+      if (text) {
+        try { json = JSON.parse(text); } catch {}
+      }
+      if (!res.ok) {
+        return {
+          __httpError: res.status,
+          message: json?.message || json?.errorMessage || json?.error?.message || (typeof json?.error === 'string' ? json.error : '') || text.slice(0, 200),
+        };
+      }
+      if (!json) return { __malformed: true, message: 'invalid JSON' };
+      return json;
     })()
-  `);
+  `));
+    } catch (error) {
+        throw new CommandExecutionError(`Pixiv request failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
     if (data?.__httpError) {
         const status = data.__httpError;
         if (status === 401 || status === 403) {
             throw new AuthRequiredError(PIXIV_DOMAIN, 'Authentication required — please log in to Pixiv in Chrome');
         }
+        const message = extractPixivErrorMessage(data);
         if (status === 404) {
-            throw new CommandExecutionError(opts.notFoundMsg || `Pixiv resource not found (HTTP 404)`);
+            throw new CommandExecutionError(message || opts.notFoundMsg || `Pixiv resource not found (HTTP 404)`);
         }
-        throw new CommandExecutionError(`Pixiv request failed (HTTP ${status})`);
+        throw new CommandExecutionError(message ? `Pixiv request failed (HTTP ${status}): ${message}` : `Pixiv request failed (HTTP ${status})`);
+    }
+    if (!data || Array.isArray(data) || typeof data !== 'object' || data.__malformed) {
+        throw new CommandExecutionError('Pixiv request returned malformed JSON payload');
+    }
+    if (data.error === true) {
+        throw new CommandExecutionError(extractPixivErrorMessage(data) || 'Pixiv API returned an error');
+    }
+    if (!('body' in data)) {
+        throw new CommandExecutionError('Pixiv request returned malformed API payload');
     }
     return data?.body;
 }

package/clis/suno/generate.js

@@ -120,6 +120,11 @@ export const generateCommand = cli({
         const title = titleSource.replace(/\s+/g, ' ').trim().slice(0, 60) || 'Untitled';
 
         const session = await ensureSunoSession(page);
+        if (!session.planId) {
+            throw new CommandExecutionError(
+                `Suno generation needs a resolved plan id for the user_tier field, but billing/info did not surface one for this account (subscription_type=${session.planKey}). Verify the account is active at ${SUNO_URL}/account, then retry.`,
+            );
+        }
         const deviceId = session.deviceId;
         const captcha = await checkSunoCaptcha(page, deviceId);
         if (!captcha?.ok) {

package/clis/suno/generate.test.js

@@ -94,6 +94,15 @@ describe('suno generate argument validation', () => {
         });
     });
 
+    it('refuses to submit when planId is null (free-tier without resolved user_tier) (#1704)', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ ...okSession, planId: null, planKey: 'free' });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('plan id'),
+        });
+        expect(mocks.submitSunoGeneration).not.toHaveBeenCalled();
+    });
+
     it('refuses to submit when credits are below the per-song minimum', async () => {
         mocks.ensureSunoSession.mockResolvedValue({ ...okSession, totalCreditsAvailable: 5, breakdown: { ...okSession.breakdown, monthlyRemaining: 5 } });
         await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({

package/clis/suno/status.js

@@ -49,8 +49,9 @@ export const statusCommand = cli({
             captcha = { required: true };
         }
         const b = session.breakdown;
-        // ensureSunoSession guarantees planId; planKey is fetched from the same
-        // billing/info response and is always populated for an active account.
+        // ensureSunoSession surfaces planKey derived from billing/info's
+        // subscription_type vs plans[] lookup; planId may be null for accounts
+        // whose plan cannot be resolved against plans[] (e.g., new schema fields).
         return [{
             Status: 'Connected',
             Plan: session.planKey,

package/clis/suno/utils.js

@@ -136,6 +136,37 @@ function sunoHeadersJs(deviceId, extra = {}) {
 // Session bootstrap.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Parse studio-api-prod billing/info. Inlined into the page IIFE via
+ * toString() so the same parser runs in Node tests and the browser.
+ */
+export function parseSunoBillingInfo(data) {
+    const packCredits = (data?.credit_packs || []).reduce((s, p) => s + (p?.amount ?? p?.credits ?? 0), 0);
+    const monthlyRemaining = Math.max(0, (data?.monthly_limit ?? 0) - (data?.monthly_usage ?? 0));
+    const totalCreditsAvailable = typeof data?.total_credits_left === 'number'
+        ? data.total_credits_left
+        : (data?.credits ?? 0) + packCredits + monthlyRemaining;
+    const plans = Array.isArray(data?.plans) ? data.plans : [];
+    const subscriptionKey = typeof data?.subscription_type === 'string' && data.subscription_type
+        ? data.subscription_type
+        : null;
+    const currentPlan = subscriptionKey
+        ? plans.find((p) => p?.plan_key === subscriptionKey)
+        : plans.find((p) => p?.plan_key === 'free');
+    return {
+        planId: currentPlan?.id || data?.plan?.id || null,
+        planKey: currentPlan?.plan_key || data?.plan?.plan_key || (subscriptionKey ?? 'free'),
+        totalCreditsAvailable,
+        breakdown: {
+            pack: data?.credits ?? 0,
+            purchasedPacks: packCredits,
+            monthlyRemaining,
+            monthlyLimit: data?.monthly_limit ?? 0,
+            monthlyUsed: data?.monthly_usage ?? 0,
+        },
+    };
+}
+
 export async function ensureSunoSession(page) {
     await page.goto(`${SUNO_URL}/me`, { settleMs: 2000 });
     // OneTrust consent banner can block the page; dismiss it if present.
@@ -163,27 +194,8 @@ export async function ensureSunoSession(page) {
             } catch (e) {
                 return { ok: false, error: 'Malformed billing/info JSON: ' + String(e).slice(0, 200) };
             }
-            // Suno tracks credits across three buckets:
-            //   - data.credits          : leftover one-time pack credits (often 0)
-            //   - monthly subscription  : (monthly_limit - monthly_usage)
-            //   - data.credit_packs[]   : purchased packs not yet exhausted
-            // The web UI's "credits remaining" pill is the sum of all three.
-            const packCredits = (data?.credit_packs || []).reduce((s, p) => s + (p?.credits ?? 0), 0);
-            const monthlyRemaining = Math.max(0, (data?.monthly_limit ?? 0) - (data?.monthly_usage ?? 0));
-            const totalCreditsAvailable = (data?.credits ?? 0) + packCredits + monthlyRemaining;
-            return {
-                ok: true,
-                planId: data?.plan?.id || null,
-                planKey: data?.plan?.plan_key || null,
-                totalCreditsAvailable,
-                breakdown: {
-                    pack: data?.credits ?? 0,
-                    purchasedPacks: packCredits,
-                    monthlyRemaining,
-                    monthlyLimit: data?.monthly_limit ?? 0,
-                    monthlyUsed: data?.monthly_usage ?? 0,
-                },
-            };
+            const parse = ${parseSunoBillingInfo.toString()};
+            return { ok: true, ...parse(data) };
         } catch (e) {
             return { ok: false, error: String(e).slice(0, 200) };
         }
@@ -196,9 +208,6 @@ export async function ensureSunoSession(page) {
         }
         throw new CommandExecutionError(`Suno session check failed (${detail}).`);
     }
-    if (!result.planId) {
-        throw new CommandExecutionError('Suno billing/info returned no plan id — cannot construct user_tier for generation request.');
-    }
     return { ...result, deviceId };
 }
 

package/clis/suno/utils.test.js

@@ -16,6 +16,7 @@ import {
     unwrapEvaluateResult,
     pollSunoClips,
     ensureSunoSession,
+    parseSunoBillingInfo,
 } from './utils.js';
 
 describe('suno utils — parseFormats', () => {
@@ -160,6 +161,84 @@ describe('suno utils — unwrapEvaluateResult', () => {
     });
 });
 
+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) => {
@@ -190,6 +269,33 @@ describe('suno utils — ensureSunoSession typed failures', () => {
             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', () => {

package/clis/twitter/followers.js

@@ -1,4 +1,4 @@
-import { ArgumentError, AuthRequiredError, selectorError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError, selectorError, EmptyResultError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { normalizeTwitterScreenName, unwrapBrowserResult } from './shared.js';
 
@@ -161,7 +161,11 @@ cli({
         const seen = new Set();
         let sameCount = 0;
         while (allFollowers.length < limit && sameCount < 3) {
-            const followers = await extractFollowersFromDOM(page);
+            const rawFollowers = await extractFollowersFromDOM(page);
+            if (!Array.isArray(rawFollowers)) {
+                throw new CommandExecutionError('Twitter followers extraction returned malformed rows');
+            }
+            const followers = rawFollowers;
             const newFollowers = followers.filter(f => !seen.has(f.screen_name));
             for (const f of newFollowers) {
                 seen.add(f.screen_name);

package/clis/twitter/followers.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
-import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { __test__ } from './followers.js';
 
 describe('twitter followers command', () => {
@@ -41,4 +41,22 @@ describe('twitter followers command', () => {
         expect(page.goto).toHaveBeenCalledWith('https://x.com/home');
         expect(page.goto).not.toHaveBeenCalledWith('https://x.com/home/followers');
     });
+
+    it('typed-fails instead of throwing "filter is not a function" when extractFollowersFromDOM returns a non-array', async () => {
+        const command = getRegistry().get('twitter/followers');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn(async (script) => {
+                const text = String(script);
+                if (text.includes('AppTabBar_Profile_Link')) return '/viewer';
+                if (text.includes('/followers') && text.includes('click')) return true;
+                if (text.includes('UserCell')) return undefined;
+                return undefined;
+            }),
+        };
+
+        await expect(command.func(page, { user: 'someone', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
 });