@jackwener/opencli 1.7.22 → 1.8.0

package/clis/linkedin-learning/course.test.js

@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './course.js';
+
+const { parseSlug, parseCourse } = await import('./course.js').then((m) => m.__test__);
+
+function makePage({ evaluateResult, cookies = [{ name: 'JSESSIONID', value: '"ajax:abc"' }] } = {}) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        getCookies: vi.fn().mockResolvedValue(cookies),
+        evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    };
+}
+
+describe('linkedin-learning course', () => {
+    it('accepts a bare slug', () => {
+        expect(parseSlug('agentic-ai-build')).toBe('agentic-ai-build');
+    });
+
+    it('extracts a slug from a full /learning/<slug> URL', () => {
+        expect(parseSlug('https://www.linkedin.com/learning/agentic-ai-build/?foo=1'))
+            .toBe('agentic-ai-build');
+    });
+
+    it('rejects non-LinkedIn Learning URLs before navigation', () => {
+        expect(() => parseSlug('https://evil.example/learning/agentic-ai-build')).toThrow(ArgumentError);
+        expect(() => parseSlug('https://www.linkedin.com/feed/update/123')).toThrow(ArgumentError);
+    });
+
+    it('rejects empty or invalid slugs with ArgumentError', () => {
+        expect(() => parseSlug('')).toThrow(ArgumentError);
+        expect(() => parseSlug('   ')).toThrow(ArgumentError);
+        expect(() => parseSlug('not a slug!')).toThrow(ArgumentError);
+    });
+
+    it('maps a course detail element to the canonical row shape', () => {
+        const el = {
+            title: 'Agentic AI: Build Your First Agentic AI System',
+            description: { text: 'Dive into agentic AI...' },
+            duration: { duration: 3932, unit: 'SECOND' },
+            difficultyLevel: 'Intermediate',
+            videosCount: 18,
+            rating: { averageRating: 4.5, ratingCount: 259 },
+            activatedAt: 1774569600000,
+        };
+        const row = parseCourse(el, 'agentic-ai-build-your-first-agentic-ai-system');
+        expect(row.title).toBe('Agentic AI: Build Your First Agentic AI System');
+        expect(row.slug).toBe('agentic-ai-build-your-first-agentic-ai-system');
+        expect(row.description).toBe('Dive into agentic AI...');
+        expect(row.difficulty).toBe('Intermediate');
+        expect(row.duration_sec).toBe('3932');
+        expect(row.videos_count).toBe(18);
+        expect(row.rating).toBe('4.50');
+        expect(row.rating_count).toBe(259);
+        expect(row.released).toBe('2026-03-27');
+        expect(row.url).toBe('https://www.linkedin.com/learning/agentic-ai-build-your-first-agentic-ai-system');
+    });
+
+    it('handles description as a bare string', () => {
+        const row = parseCourse({ title: 't', description: 'plain string' }, 'x');
+        expect(row.description).toBe('plain string');
+    });
+
+    it('preserves the full course description', () => {
+        const text = 'x'.repeat(350);
+        const row = parseCourse({ title: 't', description: { text } }, 'x');
+        expect(row.description).toBe(text);
+    });
+
+    it('returns empty fields when upstream omits them', () => {
+        const row = parseCourse({ title: 't' }, 'x');
+        expect(row.title).toBe('t');
+        expect(row.duration_sec).toBe('');
+        expect(row.rating).toBe('');
+        expect(row.released).toBe('');
+    });
+
+    it('returns null when upstream omits the core title evidence', () => {
+        expect(parseCourse({}, 'x')).toBeNull();
+        expect(parseCourse({ title: '   ' }, 'x')).toBeNull();
+    });
+
+    it('throws AuthRequiredError when JSESSIONID is missing', async () => {
+        const cmd = getRegistry().get('linkedin-learning/course');
+        const page = makePage({ cookies: [], evaluateResult: { json: { elements: [{}] } } });
+        await expect(cmd.func(page, { slug: 'agentic-ai-build' })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('throws EmptyResultError when no element matches the slug', async () => {
+        const cmd = getRegistry().get('linkedin-learning/course');
+        const page = makePage({ evaluateResult: { json: { elements: [] } } });
+        await expect(cmd.func(page, { slug: 'agentic-ai-build' })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('throws CommandExecutionError when the elements array is missing', async () => {
+        const cmd = getRegistry().get('linkedin-learning/course');
+        const page = makePage({ evaluateResult: { json: { data: {} } } });
+        await expect(cmd.func(page, { slug: 'agentic-ai-build' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when the first detail element is malformed', async () => {
+        const cmd = getRegistry().get('linkedin-learning/course');
+        const page = makePage({ evaluateResult: { json: { elements: [{}] } } });
+        await expect(cmd.func(page, { slug: 'agentic-ai-build' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError on fetch errors', async () => {
+        const cmd = getRegistry().get('linkedin-learning/course');
+        const page = makePage({ evaluateResult: { error: 'HTTP 500' } });
+        await expect(cmd.func(page, { slug: 'agentic-ai-build' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});

package/clis/linkedin-learning/search.js

@@ -0,0 +1,155 @@
+/**
+ * LinkedIn Learning search via the public learning-api REST endpoint.
+ * Shares cookie session with linkedin.com; no Commercial Use Limit.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const DOMAIN = 'www.linkedin.com';
+const MAX_LIMIT = 50;
+
+function normalizeWhitespace(value) {
+    return String(value ?? '').replace(/[  ]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function parseLimit(value) {
+    if (value === undefined || value === null || value === '') return 10;
+    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 unwrapEvaluateResult(payload) {
+    if (payload && typeof payload === 'object' && 'data' in payload && 'session' in payload) return payload.data;
+    return payload;
+}
+
+function buildFetchScript(url, csrf) {
+    return String.raw`(async () => {
+    try {
+      const res = await fetch(${JSON.stringify(url)}, {
+        credentials: 'include',
+        headers: {
+          'csrf-token': ${JSON.stringify(csrf)},
+          'x-restli-protocol-version': '2.0.0',
+          accept: 'application/json',
+        },
+      });
+      if (res.status === 401 || res.status === 403) return { authRequired: true, status: res.status };
+      if (!res.ok) return { error: 'HTTP ' + res.status };
+      return { json: await res.json() };
+    } catch (e) {
+      return { error: 'fetch failed: ' + ((e && e.message) || String(e)) };
+    }
+  })()`;
+}
+
+function parseAuthors(authors) {
+    if (!Array.isArray(authors)) return '';
+    return authors
+        .map((a) => normalizeWhitespace((a?.firstName ?? '') + ' ' + (a?.lastName ?? '')))
+        .filter(Boolean)
+        .join(', ');
+}
+
+function durationSeconds(length) {
+    const ts = length?.['com.linkedin.common.TimeSpan'];
+    if (!ts || ts.unit !== 'SECOND') return '';
+    return String(ts.duration ?? '');
+}
+
+function averageRating(rating) {
+    if (!rating) return '';
+    if (typeof rating.averageRating === 'number') return rating.averageRating.toFixed(2);
+    if (typeof rating.ratingSum === 'number' && typeof rating.ratingCount === 'number' && rating.ratingCount > 0) {
+        return (rating.ratingSum / rating.ratingCount).toFixed(2);
+    }
+    return '';
+}
+
+function parseRow(el, rank) {
+    const type = el?.entityType || '';
+    const slug = el?.slug || '';
+    if (!slug) return null;
+    return {
+        rank,
+        type,
+        title: el?.headline?.title?.text || '',
+        instructor: parseAuthors(el?.authors),
+        difficulty: el?.difficultyLevel || '',
+        duration_sec: durationSeconds(el?.length),
+        rating: averageRating(el?.rating),
+        rating_count: el?.rating?.ratingCount ?? '',
+        viewers: el?.viewerCount ?? '',
+        url: slug ? `https://www.linkedin.com/learning/${slug}` : '',
+    };
+}
+
+cli({
+    site: 'linkedin-learning',
+    name: 'search',
+    access: 'read',
+    description: 'Search LinkedIn Learning courses, videos, and learning paths by keyword',
+    domain: DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'keywords', type: 'string', required: true, positional: true, help: 'Search keywords, e.g. "AI agent"' },
+        { name: 'limit', type: 'int', default: 10, help: `Maximum results to return (1-${MAX_LIMIT})` },
+    ],
+    columns: ['rank', 'type', 'title', 'instructor', 'difficulty', 'duration_sec', 'rating', 'rating_count', 'viewers', 'url'],
+    func: async (page, args) => {
+        if (!page) throw new CommandExecutionError('Browser session required for linkedin-learning search');
+        const keywords = normalizeWhitespace(args.keywords);
+        if (!keywords) throw new ArgumentError('--keywords is required');
+        const limit = parseLimit(args.limit);
+
+        await page.goto('https://www.linkedin.com/learning/');
+        await page.wait(3);
+
+        const cookies = await page.getCookies({ url: 'https://www.linkedin.com' });
+        const jsession = cookies.find((c) => c.name === 'JSESSIONID')?.value;
+        if (!jsession) {
+            throw new AuthRequiredError(DOMAIN, 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn in the browser.');
+        }
+        const csrf = jsession.replace(/^"|"$/g, '');
+
+        const url = `https://www.linkedin.com/learning-api/searchV2?keywords=${encodeURIComponent(keywords)}&q=keywords`;
+        const result = unwrapEvaluateResult(await page.evaluate(buildFetchScript(url, csrf)));
+        if (result?.authRequired) {
+            throw new AuthRequiredError(DOMAIN, `LinkedIn Learning auth failed (HTTP ${result.status ?? ''}).`);
+        }
+        if (!result?.json) {
+            throw new CommandExecutionError(`LinkedIn Learning searchV2 failed: ${result?.error ?? 'no payload'}`);
+        }
+        const elements = result.json?.elements;
+        if (!Array.isArray(elements)) {
+            throw new CommandExecutionError('LinkedIn Learning searchV2 returned malformed payload: missing elements array');
+        }
+        if (elements.length === 0) {
+            throw new EmptyResultError(`No LinkedIn Learning results for "${keywords}"`);
+        }
+        const rows = [];
+        for (const el of elements) {
+            if (rows.length >= limit) break;
+            const row = parseRow(el, rows.length + 1);
+            if (row) rows.push(row);
+        }
+        if (rows.length === 0) {
+            throw new CommandExecutionError('LinkedIn Learning searchV2 returned no parseable rows with slug identity');
+        }
+        return rows;
+    },
+});
+
+export const __test__ = {
+    normalizeWhitespace,
+    parseLimit,
+    parseAuthors,
+    durationSeconds,
+    averageRating,
+    parseRow,
+    buildFetchScript,
+};

package/clis/linkedin-learning/search.test.js

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './search.js';
+
+const { parseLimit, parseAuthors, durationSeconds, averageRating, parseRow, buildFetchScript } = await import('./search.js').then((m) => m.__test__);
+
+function makePage({ evaluateResult, cookies = [{ name: 'JSESSIONID', value: '"ajax:abc"' }] } = {}) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        getCookies: vi.fn().mockResolvedValue(cookies),
+        evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    };
+}
+
+describe('linkedin-learning search', () => {
+    it('validates --limit without silent clamping', () => {
+        expect(parseLimit(undefined)).toBe(10);
+        expect(parseLimit(1)).toBe(1);
+        expect(parseLimit(50)).toBe(50);
+        expect(() => parseLimit(0)).toThrow(ArgumentError);
+        expect(() => parseLimit(51)).toThrow(ArgumentError);
+        expect(() => parseLimit('abc')).toThrow(ArgumentError);
+        expect(() => parseLimit(1.5)).toThrow(ArgumentError);
+    });
+
+    it('joins author first/last names', () => {
+        expect(parseAuthors([{ firstName: 'Jane', lastName: 'Doe' }])).toBe('Jane Doe');
+        expect(parseAuthors([{ firstName: 'A', lastName: 'B' }, { firstName: 'C', lastName: 'D' }])).toBe('A B, C D');
+        expect(parseAuthors([])).toBe('');
+        expect(parseAuthors(undefined)).toBe('');
+    });
+
+    it('extracts duration from TimeSpan only when unit is SECOND', () => {
+        expect(durationSeconds({ 'com.linkedin.common.TimeSpan': { duration: 600, unit: 'SECOND' } })).toBe('600');
+        expect(durationSeconds({ 'com.linkedin.common.TimeSpan': { duration: 10, unit: 'MINUTE' } })).toBe('');
+        expect(durationSeconds(undefined)).toBe('');
+    });
+
+    it('computes average rating from sum/count when averageRating is missing', () => {
+        expect(averageRating({ ratingSum: 1165, ratingCount: 259 })).toBe('4.50');
+        expect(averageRating({ averageRating: 4.32 })).toBe('4.32');
+        expect(averageRating({ ratingSum: 0, ratingCount: 0 })).toBe('');
+        expect(averageRating(undefined)).toBe('');
+    });
+
+    it('maps a search result element to the canonical row shape', () => {
+        const el = {
+            entityType: 'COURSE',
+            slug: 'agentic-ai-build-your-first-agentic-ai-system',
+            headline: { title: { text: 'Agentic AI: Build Your First Agentic AI System' } },
+            authors: [{ firstName: 'Aishwarya', lastName: 'Naresh Reganti' }],
+            difficultyLevel: 'INTERMEDIATE',
+            length: { 'com.linkedin.common.TimeSpan': { duration: 3932, unit: 'SECOND' } },
+            rating: { ratingSum: 1165, ratingCount: 259 },
+            viewerCount: 25323,
+        };
+        expect(parseRow(el, 1)).toEqual({
+            rank: 1,
+            type: 'COURSE',
+            title: 'Agentic AI: Build Your First Agentic AI System',
+            instructor: 'Aishwarya Naresh Reganti',
+            difficulty: 'INTERMEDIATE',
+            duration_sec: '3932',
+            rating: '4.50',
+            rating_count: 259,
+            viewers: 25323,
+            url: 'https://www.linkedin.com/learning/agentic-ai-build-your-first-agentic-ai-system',
+        });
+    });
+
+    it('drops rows without slug identity', () => {
+        const row = parseRow({ entityType: 'COURSE', headline: { title: { text: 't' } } }, 2);
+        expect(row).toBeNull();
+    });
+
+    it('escapes the URL and csrf into the fetch script as literal strings', () => {
+        const s = buildFetchScript('https://www.linkedin.com/learning-api/searchV2?keywords=AI', 'csrf-token-value');
+        expect(s).toContain('"https://www.linkedin.com/learning-api/searchV2?keywords=AI"');
+        expect(s).toContain('"csrf-token-value"');
+        expect(s).toContain("'x-restli-protocol-version': '2.0.0'");
+        expect(s).toContain('authRequired: true');
+    });
+
+    it('throws AuthRequiredError when JSESSIONID cookie is missing', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ cookies: [], evaluateResult: { json: { elements: [] } } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('throws AuthRequiredError when the fetch returns 403', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ evaluateResult: { authRequired: true, status: 403 } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('throws CommandExecutionError when the upstream payload is empty', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ evaluateResult: { error: 'fetch failed: socket' } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError when zero elements come back', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ evaluateResult: { json: { elements: [] } } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('throws CommandExecutionError when the elements array is missing', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ evaluateResult: { json: { data: {} } } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when elements lack slug identity', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ evaluateResult: { json: { elements: [{ headline: { title: { text: 'No slug' } } }] } } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects empty keywords with ArgumentError before navigation', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const page = makePage({ evaluateResult: { json: { elements: [] } } });
+        await expect(cmd.func(page, { keywords: '   ', limit: 5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('returns ranked rows when the API responds normally', async () => {
+        const cmd = getRegistry().get('linkedin-learning/search');
+        const elements = [
+            { entityType: 'COURSE', slug: 'a', headline: { title: { text: 'Course A' } }, authors: [{ firstName: 'Inst', lastName: 'A' }], difficultyLevel: 'BEGINNER', length: { 'com.linkedin.common.TimeSpan': { duration: 100, unit: 'SECOND' } } },
+            { entityType: 'COURSE', headline: { title: { text: 'No slug' } } },
+            { entityType: 'VIDEO', slug: 'b', headline: { title: { text: 'Video B' } } },
+        ];
+        const page = makePage({ evaluateResult: { json: { elements } } });
+        const rows = await cmd.func(page, { keywords: 'test', limit: 5 });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].rank).toBe(1);
+        expect(rows[0].title).toBe('Course A');
+        expect(rows[1].title).toBe('Video B');
+        expect(rows[1].url).toBe('https://www.linkedin.com/learning/b');
+    });
+});

package/clis/linkedin-learning/trending.js

@@ -0,0 +1,133 @@
+/**
+ * LinkedIn Learning personalized recommendations via the
+ * feedRecommendationGroups carousels endpoint. The `learner` view
+ * returns a small set of carousels (e.g. "Top picks for you"); this
+ * command flattens the cards across them into a ranked list.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const DOMAIN = 'www.linkedin.com';
+const MAX_LIMIT = 50;
+const MAX_PER_CAROUSEL = 25;
+
+function parseLimit(value) {
+    if (value === undefined || value === null || value === '') return 10;
+    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 unwrapEvaluateResult(payload) {
+    if (payload && typeof payload === 'object' && 'data' in payload && 'session' in payload) return payload.data;
+    return payload;
+}
+
+function buildFetchScript(url, csrf) {
+    return String.raw`(async () => {
+    try {
+      const res = await fetch(${JSON.stringify(url)}, {
+        credentials: 'include',
+        headers: {
+          'csrf-token': ${JSON.stringify(csrf)},
+          'x-restli-protocol-version': '2.0.0',
+          accept: 'application/json',
+        },
+      });
+      if (res.status === 401 || res.status === 403) return { authRequired: true, status: res.status };
+      if (!res.ok) return { error: 'HTTP ' + res.status };
+      return { json: await res.json() };
+    } catch (e) {
+      return { error: 'fetch failed: ' + ((e && e.message) || String(e)) };
+    }
+  })()`;
+}
+
+function parseCard(card, group, rank) {
+    const slug = card?.slug || '';
+    if (!slug) return null;
+    return {
+        rank,
+        group: group?.title?.text || group?.annotation || '',
+        type: card?.entityType || card?.localizedEntityName || '',
+        title: card?.title?.text || card?.headline?.title?.text || card?.headline?.text || '',
+        difficulty: card?.difficultyLevel || '',
+        viewers: card?.viewerCount ?? '',
+        url: slug ? `https://www.linkedin.com/learning/${slug}` : '',
+    };
+}
+
+cli({
+    site: 'linkedin-learning',
+    name: 'trending',
+    access: 'read',
+    description: 'Browse LinkedIn Learning recommended courses across personalized carousels',
+    domain: DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: 10, help: `Maximum results to return (1-${MAX_LIMIT})` },
+    ],
+    columns: ['rank', 'group', 'type', 'title', 'difficulty', 'viewers', 'url'],
+    func: async (page, args) => {
+        if (!page) throw new CommandExecutionError('Browser session required for linkedin-learning trending');
+        const limit = parseLimit(args.limit);
+
+        await page.goto('https://www.linkedin.com/learning/');
+        await page.wait(3);
+
+        const cookies = await page.getCookies({ url: 'https://www.linkedin.com' });
+        const jsession = cookies.find((c) => c.name === 'JSESSIONID')?.value;
+        if (!jsession) {
+            throw new AuthRequiredError(DOMAIN, 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn in the browser.');
+        }
+        const csrf = jsession.replace(/^"|"$/g, '');
+
+        const url = `https://www.linkedin.com/learning-api/feedRecommendationGroups?countPerCarousel=${MAX_PER_CAROUSEL}&q=learner`;
+        const result = unwrapEvaluateResult(await page.evaluate(buildFetchScript(url, csrf)));
+        if (result?.authRequired) {
+            throw new AuthRequiredError(DOMAIN, `LinkedIn Learning auth failed (HTTP ${result.status ?? ''}).`);
+        }
+        if (!result?.json) {
+            throw new CommandExecutionError(`LinkedIn Learning feedRecommendationGroups failed: ${result?.error ?? 'no payload'}`);
+        }
+        const groups = result.json?.elements;
+        if (!Array.isArray(groups)) {
+            throw new CommandExecutionError('LinkedIn Learning feedRecommendationGroups returned malformed payload: missing elements array');
+        }
+        const rows = [];
+        const seen = new Set();
+        let rank = 1;
+        let sawCards = false;
+        for (const group of groups) {
+            const carousels = Array.isArray(group?.carousels) ? group.carousels : [];
+            for (const carousel of carousels) {
+                const cards = Array.isArray(carousel?.cards) ? carousel.cards : [];
+                for (const card of cards) {
+                    sawCards = true;
+                    if (rows.length >= limit) break;
+                    const slug = card?.slug;
+                    if (!slug || seen.has(slug)) continue;
+                    seen.add(slug);
+                    const row = parseCard(card, carousel, rank);
+                    if (!row) continue;
+                    rows.push(row);
+                    rank += 1;
+                }
+                if (rows.length >= limit) break;
+            }
+            if (rows.length >= limit) break;
+        }
+        if (rows.length === 0) {
+            if (sawCards) {
+                throw new CommandExecutionError('LinkedIn Learning feedRecommendationGroups returned no parseable cards with slug identity');
+            }
+            throw new EmptyResultError('LinkedIn Learning returned no personalized recommendations');
+        }
+        return rows;
+    },
+});
+
+export const __test__ = { parseLimit, parseCard };

package/clis/linkedin-learning/trending.test.js

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './trending.js';
+
+const { parseLimit, parseCard } = await import('./trending.js').then((m) => m.__test__);
+
+function makePage({ evaluateResult, cookies = [{ name: 'JSESSIONID', value: '"ajax:abc"' }] } = {}) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        getCookies: vi.fn().mockResolvedValue(cookies),
+        evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    };
+}
+
+describe('linkedin-learning trending', () => {
+    it('validates --limit without silent clamping', () => {
+        expect(parseLimit(undefined)).toBe(10);
+        expect(parseLimit(50)).toBe(50);
+        expect(() => parseLimit(0)).toThrow(ArgumentError);
+        expect(() => parseLimit(51)).toThrow(ArgumentError);
+    });
+
+    it('maps a carousel card to the canonical row shape', () => {
+        const card = {
+            entityType: 'COURSE',
+            slug: 'storytelling-editing',
+            difficultyLevel: 'BEGINNER_INTERMEDIATE',
+            description: { text: 'Go beyond basic video editing.' },
+            viewerCount: 12345,
+            headline: { title: { text: 'The Art of Storytelling through Editing' } },
+        };
+        const group = { annotation: 'TOP_PICKS', title: { text: 'Top picks for you' } };
+        expect(parseCard(card, group, 1)).toEqual({
+            rank: 1,
+            group: 'Top picks for you',
+            type: 'COURSE',
+            title: 'The Art of Storytelling through Editing',
+            difficulty: 'BEGINNER_INTERMEDIATE',
+            viewers: 12345,
+            url: 'https://www.linkedin.com/learning/storytelling-editing',
+        });
+    });
+
+    it('drops cards without slug identity', () => {
+        expect(parseCard({ title: { text: 'No slug' } }, { title: { text: 'G' } }, 1)).toBeNull();
+    });
+
+    it('flattens carousels and dedups cards across them', async () => {
+        const cmd = getRegistry().get('linkedin-learning/trending');
+        const page = makePage({
+            evaluateResult: {
+                json: {
+                    elements: [{
+                        carousels: [
+                            {
+                                title: { text: 'Top picks' },
+                                cards: [
+                                    { slug: 'a', headline: { title: { text: 'Course A' } } },
+                                    { headline: { title: { text: 'No slug' } } },
+                                    { slug: 'b', headline: { title: { text: 'Course B' } } },
+                                ],
+                            },
+                            {
+                                title: { text: 'Trending in your network' },
+                                cards: [
+                                    { slug: 'a', headline: { title: { text: 'Dup of A' } } },
+                                    { slug: 'c', headline: { title: { text: 'Course C' } } },
+                                ],
+                            },
+                        ],
+                    }],
+                },
+            },
+        });
+        const rows = await cmd.func(page, { limit: 5 });
+        expect(rows.map((r) => r.title)).toEqual(['Course A', 'Course B', 'Course C']);
+        expect(rows.map((r) => r.rank)).toEqual([1, 2, 3]);
+        expect(rows[0].group).toBe('Top picks');
+        expect(rows[2].group).toBe('Trending in your network');
+    });
+
+    it('respects --limit', async () => {
+        const cmd = getRegistry().get('linkedin-learning/trending');
+        const cards = Array.from({ length: 6 }, (_, i) => ({ slug: `s${i}`, headline: { title: { text: `T${i}` } } }));
+        const page = makePage({
+            evaluateResult: {
+                json: { elements: [{ carousels: [{ title: { text: 'G' }, cards }] }] },
+            },
+        });
+        const rows = await cmd.func(page, { limit: 3 });
+        expect(rows).toHaveLength(3);
+    });
+
+    it('throws AuthRequiredError when JSESSIONID is missing', async () => {
+        const cmd = getRegistry().get('linkedin-learning/trending');
+        const page = makePage({ cookies: [], evaluateResult: { json: { elements: [] } } });
+        await expect(cmd.func(page, { limit: 5 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('throws EmptyResultError when no carousels yield cards', async () => {
+        const cmd = getRegistry().get('linkedin-learning/trending');
+        const page = makePage({ evaluateResult: { json: { elements: [{ carousels: [] }] } } });
+        await expect(cmd.func(page, { limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('throws CommandExecutionError when the elements array is missing', async () => {
+        const cmd = getRegistry().get('linkedin-learning/trending');
+        const page = makePage({ evaluateResult: { json: { data: {} } } });
+        await expect(cmd.func(page, { limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError when cards lack slug identity', async () => {
+        const cmd = getRegistry().get('linkedin-learning/trending');
+        const page = makePage({
+            evaluateResult: {
+                json: { elements: [{ carousels: [{ title: { text: 'G' }, cards: [{ headline: { title: { text: 'No slug' } } }] }] }] },
+            },
+        });
+        await expect(cmd.func(page, { limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});