@jackwener/opencli 1.7.22 → 1.8.0

package/clis/linkedin/connect.test.js

@@ -0,0 +1,213 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import './connect.js';
+
+const {
+    normalizeName,
+    matchInvitationName,
+    canonicalizeLinkedInProfileUrl,
+    canonicalizeLinkedInInviteUrl,
+    unwrapEvaluateResult,
+    clampNote,
+    assessProfileSafety,
+} = await import('./connect.js').then((m) => m.__test__);
+
+function makeFakePage(probe, sendResult = { ok: true, status: 'sent', reason: 'connection_request_sent' }) {
+    return {
+        goto: vi.fn(async () => undefined),
+        wait: vi.fn(async () => undefined),
+        evaluate: vi.fn(async (script) => {
+            const text = String(script);
+            if (text.includes('custom-message') || text.includes('invite_dialog_not_found')) return sendResult;
+            return probe;
+        }),
+    };
+}
+
+function makeSequentialFakePage(values) {
+    let index = 0;
+    return {
+        goto: vi.fn(async () => undefined),
+        wait: vi.fn(async () => undefined),
+        evaluate: vi.fn(async (script) => {
+            const text = String(script);
+            if (text.includes('custom-message') || text.includes('invite_dialog_not_found')) return { ok: true, status: 'sent', reason: 'connection_request_sent' };
+            const value = values[Math.min(index, values.length - 1)];
+            index += 1;
+            return value;
+        }),
+    };
+}
+
+describe('linkedin connect helpers', () => {
+    it('normalizes names and profile URLs', () => {
+        expect(normalizeName('Jane Doe • 2nd degree connection')).toBe('jane doe');
+        expect(matchInvitationName('Jane Doe, P.Eng.', ' jane   doe ')).toBe(true);
+        expect(matchInvitationName('Jane Q. Doe', 'Jane Doe')).toBe(true);
+        expect(matchInvitationName('Janet Doe', 'Jane Doe')).toBe(false);
+        expect(canonicalizeLinkedInProfileUrl('https://www.linkedin.com/in/jane/?mini=true#x'))
+            .toBe('https://www.linkedin.com/in/jane/');
+        expect(canonicalizeLinkedInProfileUrl('https://ca.linkedin.com/in/jane/?mini=true#x'))
+            .toBe('https://www.linkedin.com/in/jane/');
+        expect(canonicalizeLinkedInProfileUrl('https://www.linkedin.com/company/opencli/')).toBe('');
+        expect(canonicalizeLinkedInProfileUrl('https://evil-linkedin.com/in/jane/')).toBe('');
+        expect(canonicalizeLinkedInProfileUrl('http://www.linkedin.com/in/jane/')).toBe('');
+    });
+
+    it('only accepts LinkedIn invitation route hrefs for sending', () => {
+        expect(canonicalizeLinkedInInviteUrl('/preload/custom-invite/?vanityName=jane'))
+            .toBe('https://www.linkedin.com/preload/custom-invite/?vanityName=jane');
+        expect(canonicalizeLinkedInInviteUrl('https://www.linkedin.com/feed/')).toBe('');
+        expect(canonicalizeLinkedInInviteUrl('https://evil-linkedin.com/preload/custom-invite/?vanityName=jane')).toBe('');
+    });
+
+    it('unwraps browser bridge evaluate envelopes', () => {
+        expect(unwrapEvaluateResult({ session: 'site:linkedin:1', data: { ok: true } })).toEqual({ ok: true });
+        const raw = { ok: true };
+        expect(unwrapEvaluateResult(raw)).toBe(raw);
+    });
+
+    it('enforces LinkedIn note length', () => {
+        expect(clampNote(' hello\nthere ')).toBe('hello there');
+        expect(() => clampNote('x'.repeat(301))).toThrow('--note must be 300 characters or fewer');
+    });
+
+    it('fails closed on wrong profile name, pending state, or missing connect button', () => {
+        expect(assessProfileSafety({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', connectAvailable: true }, 'Janet Doe', 'https://www.linkedin.com/in/jane/').blockReason)
+            .toBe('profile_name_mismatch');
+        expect(assessProfileSafety({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', pending: true, connectAvailable: true }, 'Jane Doe', 'https://www.linkedin.com/in/jane/').blockReason)
+            .toBe('connection_pending');
+        expect(assessProfileSafety({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/' }, 'Jane Doe', 'https://www.linkedin.com/in/jane/').blockReason)
+            .toBe('connect_button_not_found');
+    });
+
+    it('classifies routine non-connectable profiles separately from unsafe blocks', () => {
+        expect(assessProfileSafety({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', alreadyConnected: true }, 'Jane Doe', 'https://www.linkedin.com/in/jane/'))
+            .toMatchObject({ ok: false, safety: 'routine_non_connectable', connectable: false, blockReason: 'already_connected' });
+        expect(assessProfileSafety({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', pending: true }, 'Jane Doe', 'https://www.linkedin.com/in/jane/'))
+            .toMatchObject({ ok: false, safety: 'routine_non_connectable', connectable: false, blockReason: 'connection_pending' });
+        expect(assessProfileSafety({ name: 'Wrong Person', url: 'https://www.linkedin.com/in/wrong/', connectAvailable: true }, 'Jane Doe', 'https://www.linkedin.com/in/jane/'))
+            .toMatchObject({ ok: false, safety: 'unsafe_block', connectable: null, blockReason: 'profile_name_mismatch' });
+    });
+
+    it('passes only when profile url, name, and connect affordance all match', () => {
+        const result = assessProfileSafety({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/?mini=true', connectAvailable: true }, 'Jane Doe', 'https://www.linkedin.com/in/jane/');
+        expect(result).toMatchObject({ ok: true, blockReason: 'verified', actualValue: 'Jane Doe', connectable: true });
+    });
+});
+
+describe('linkedin connect command', () => {
+    it('registers as a write command and dry-runs by default', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        expect(command).toBeDefined();
+        expect(command.access).toBe('write');
+        const page = makeFakePage({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', connectAvailable: true, connectHref: '/preload/custom-invite/?vanityName=jane', buttonLabels: ['Connect'] });
+        const rows = await command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            note: 'quick note',
+        });
+        expect(rows[0]).toMatchObject({ status: 'connectable_dry_run', recipient: 'Jane Doe', reason: 'verified', connectable: true });
+        expect(page.evaluate).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns a clean not_connectable dry-run row for routine blocked states', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeFakePage({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', alreadyConnected: true, buttonLabels: ['Message'] });
+        const rows = await command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            note: 'quick note',
+        });
+        expect(rows[0]).toMatchObject({ status: 'not_connectable', recipient: 'Jane Doe', reason: 'already_connected', connectable: false });
+    });
+
+    it('does not send when recipient verification fails', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeFakePage({ name: 'Wrong Person', url: 'https://www.linkedin.com/in/wrong/', connectAvailable: true, buttonLabels: ['Connect'] });
+        await expect(command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            note: 'quick note',
+            send: true,
+        })).rejects.toBeInstanceOf(CommandExecutionError);
+        expect(page.evaluate).toHaveBeenCalledTimes(1);
+    });
+
+    it('rejects non-profile URLs before navigating', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeFakePage({});
+
+        await expect(command.func(page, {
+            'profile-url': 'https://www.linkedin.com/company/opencli/',
+            'expected-name': 'Jane Doe',
+            send: true,
+        })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('blocks send when the connect link is not LinkedIn invitation route', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeFakePage({ name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', connectAvailable: true, connectHref: 'https://www.linkedin.com/feed/', buttonLabels: ['Connect'] });
+
+        await expect(command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            send: true,
+        })).rejects.toThrow('invalid_connect_link');
+    });
+
+    it('sends only when --send is true after verification and sent-invitations confirms delivery', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeSequentialFakePage([
+            { name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', connectAvailable: true, connectHref: '/preload/custom-invite/?vanityName=jane', buttonLabels: ['Connect'] },
+            { found: true, matchedName: 'Jane Doe', matchedUrl: 'https://www.linkedin.com/in/jane/' },
+        ]);
+        const rows = await command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            note: 'quick note',
+            send: true,
+        });
+        expect(rows[0]).toMatchObject({ status: 'sent_verified', recipient: 'Jane Doe', reason: 'sent_invitation_verified', delivery_verified: true });
+        expect(page.goto).toHaveBeenCalledWith('https://www.linkedin.com/mynetwork/invitation-manager/sent/');
+    });
+
+    it('retries sent-invitations verification before reporting unverified', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeSequentialFakePage([
+            { name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', connectAvailable: true, connectHref: '/preload/custom-invite/?vanityName=jane', buttonLabels: ['Connect'] },
+            { found: false, matchedName: '', matchedUrl: '', visibleNames: ['Other Person'] },
+            { found: false, matchedName: '', matchedUrl: '', visibleNames: ['Other Person'] },
+            { found: true, matchedName: 'Jane Doe, P.Eng.', matchedUrl: '' },
+        ]);
+        const rows = await command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            note: 'quick note',
+            send: true,
+        });
+        expect(rows[0]).toMatchObject({ status: 'sent_verified', recipient: 'Jane Doe', reason: 'sent_invitation_verified', delivery_verified: true, matched_invitation_name: 'Jane Doe, P.Eng.' });
+        expect(page.goto).toHaveBeenCalledWith('https://www.linkedin.com/mynetwork/invitation-manager/sent/');
+        expect(page.evaluate).toHaveBeenCalledTimes(5);
+    });
+
+    it('does not report sent when sent-invitations verification fails after retries', async () => {
+        const command = getRegistry().get('linkedin/connect');
+        const page = makeSequentialFakePage([
+            { name: 'Jane Doe', url: 'https://www.linkedin.com/in/jane/', connectAvailable: true, connectHref: '/preload/custom-invite/?vanityName=jane', buttonLabels: ['Connect'] },
+            { found: false, matchedName: '', matchedUrl: '' },
+            { found: false, matchedName: '', matchedUrl: '' },
+            { found: false, matchedName: '', matchedUrl: '' },
+        ]);
+        const rows = await command.func(page, {
+            'profile-url': 'https://www.linkedin.com/in/jane/',
+            'expected-name': 'Jane Doe',
+            note: 'quick note',
+            send: true,
+        });
+        expect(rows[0]).toMatchObject({ status: 'send_unverified', recipient: 'Jane Doe', reason: 'sent_invitation_not_found_after_retries', delivery_verified: false });
+        expect(page.evaluate).toHaveBeenCalledTimes(5);
+    });
+});

package/clis/linkedin/inbox.js

@@ -0,0 +1,234 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const LINKEDIN_DOMAIN = 'linkedin.com';
+const MESSAGING_URL = 'https://www.linkedin.com/messaging/';
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 100;
+const DEFAULT_LIMIT = 40;
+
+// ── Why this command reads an API response instead of scraping the DOM ──
+//
+// LinkedIn's messaging UI is a realtime, virtualized SPA. Scraping the rendered
+// conversation list is brittle: rows lazy-render, the list virtualizes, and the
+// markup churns. Instead we let the page load /messaging/ exactly as a human
+// would, which makes the page fire its own `messengerConversations` GraphQL
+// call. We then re-issue that same request (URL lifted from the Performance API,
+// so the rotating queryId is always current) and parse LinkedIn's normalized
+// JSON. Same session, same origin, same request the page already makes.
+
+function unwrapEvaluateResult(payload) {
+  if (payload && typeof payload === 'object' && 'data' in payload && 'session' in payload) return payload.data;
+  return payload;
+}
+
+function threadUrl(threadId) {
+  return threadId ? `https://www.linkedin.com/messaging/thread/${threadId}/` : '';
+}
+
+// Runs in-page: locate the messengerConversations request the page already fired.
+// Prefers the category-scoped query (the primary inbox) over the sync-token query.
+function findMessagingApiUrl() {
+  if (/\/(login|checkpoint|authwall|uas)/i.test(location.pathname)) return { loginRequired: true };
+  const urls = performance.getEntriesByType('resource').map((e) => e.name);
+  const matches = (re) => urls.find((u) => /messengerConversations\.[a-f0-9]+/i.test(u) && re.test(u));
+  const url =
+    matches(/PRIMARY_INBOX/i) ||
+    matches(/conversationCategoryPredicate/i) ||
+    urls.find((u) => /messengerConversations\.[a-f0-9]+/i.test(u) && /mailboxUrn/i.test(u));
+  if (!url) return { url: null };
+  const mb = url.match(/mailboxUrn:(urn[^,)&]+)/i);
+  return { url, mailboxUrn: mb ? decodeURIComponent(mb[1]) : '' };
+}
+
+// Runs in-page: re-issue the messaging request with the session's csrf token.
+async function fetchMessagingApi(url, csrf) {
+  try {
+    const res = await fetch(url, {
+      credentials: 'include',
+      headers: {
+        'csrf-token': csrf,
+        accept: 'application/vnd.linkedin.normalized+json+2.1',
+        'x-restli-protocol-version': '2.0.0',
+      },
+    });
+    if (res.status === 401 || res.status === 403) return { authRequired: true, error: 'HTTP ' + 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)) };
+  }
+}
+
+// Parse LinkedIn's normalized messaging JSON into plain conversation rows.
+// `included` is a flat entity array; conversations reference participants and
+// messages by URN, which we resolve through a urn->entity index. Exported for
+// unit testing against a captured fixture.
+function parseConversations(normalized, mailboxUrn) {
+  if (!normalized || typeof normalized !== 'object' || Array.isArray(normalized) || !Array.isArray(normalized.included)) {
+    throw new CommandExecutionError('LinkedIn messaging API returned malformed normalized payload: missing included array');
+  }
+  const included = normalized.included;
+  const byUrn = new Map();
+  for (const o of included) {
+    if (o && o.entityUrn) byUrn.set(o.entityUrn, o);
+  }
+  const norm = (s) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+
+  const participantInfo = (p) => {
+    if (!p) return { name: '', kind: '' };
+    const pt = p.participantType || {};
+    if (pt.organization && pt.organization.name) return { name: norm(pt.organization.name.text), kind: 'organization' };
+    if (pt.member) {
+      const fn = pt.member.firstName && pt.member.firstName.text;
+      const ln = pt.member.lastName && pt.member.lastName.text;
+      return { name: norm([fn, ln].filter(Boolean).join(' ')), kind: 'member' };
+    }
+    if (pt.agent && pt.agent.name) return { name: norm(pt.agent.name.text), kind: 'agent' };
+    return { name: '', kind: '' };
+  };
+
+  const entries = [];
+  for (const conv of included) {
+    if (!conv || conv.$type !== 'com.linkedin.messenger.Conversation') continue;
+    const threadId = String(conv.backendUrn || '').replace(/^urn:li:messagingThread:/, '');
+    if (!threadId) {
+      throw new CommandExecutionError('LinkedIn messaging API returned a conversation without thread id');
+    }
+
+    const others = [];
+    let counterpartyKind = '';
+    for (const urn of conv['*conversationParticipants'] || []) {
+      const p = byUrn.get(urn);
+      if (!p) continue;
+      if (mailboxUrn && p.hostIdentityUrn === mailboxUrn) continue; // exclude the inbox owner
+      const info = participantInfo(p);
+      if (info.name) {
+        others.push(info.name);
+        if (!counterpartyKind) counterpartyKind = info.kind;
+      }
+    }
+
+    const msgUrns = (conv.messages && conv.messages['*elements']) || [];
+    const lastMsg = byUrn.get(msgUrns[0]);
+    let preview = lastMsg && lastMsg.body ? norm(lastMsg.body.text) : '';
+    if (!preview) preview = norm(conv.descriptionText || '');
+
+    const activityMs = Number(conv.lastActivityAt || 0);
+    entries.push({
+      activityMs,
+      row: {
+        thread_id: threadId,
+        person_name: conv.title ? norm(conv.title) : others.join(', '),
+        last_message_preview: preview.slice(0, 300),
+        unread: Number(conv.unreadCount || 0) > 0 || conv.read === false,
+        counterparty_type: counterpartyKind,
+        category: Array.isArray(conv.categories) ? conv.categories.join(',') : '',
+        timestamp: activityMs ? new Date(activityMs).toISOString() : '',
+      },
+    });
+  }
+  // Most-recent first; the sort key is kept off the returned row.
+  entries.sort((a, b) => b.activityMs - a.activityMs);
+  return entries.map((entry) => entry.row);
+}
+
+cli({
+  site: 'linkedin',
+  name: 'inbox',
+  access: 'read',
+  description: 'List LinkedIn messaging inbox conversations and unread messages',
+  domain: 'www.linkedin.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: 'limit', type: 'int', default: DEFAULT_LIMIT, help: 'Maximum conversations to return (1-100)' },
+    { name: 'unread-only', type: 'bool', default: false, help: 'Return only conversations with unread messages' },
+  ],
+  columns: [
+    'rank',
+    'thread_url',
+    'thread_id',
+    'person_name',
+    'last_message_preview',
+    'unread',
+    'counterparty_type',
+    'category',
+    'timestamp',
+  ],
+  func: async (page, kwargs) => {
+    // Validate --limit explicitly rather than silently clamping an out-of-range value.
+    let limit = DEFAULT_LIMIT;
+    if (kwargs.limit !== undefined && kwargs.limit !== null && kwargs.limit !== '') {
+      limit = Number(kwargs.limit);
+      if (!Number.isInteger(limit) || limit < MIN_LIMIT || limit > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be an integer between ${MIN_LIMIT} and ${MAX_LIMIT}`);
+      }
+    }
+    const unreadOnly = Boolean(kwargs['unread-only']);
+
+    await page.goto(MESSAGING_URL);
+    await page.wait(10);
+
+    // Locate the messaging API request the page fired on load; retry once if the
+    // SPA was slow to issue it.
+    let located = unwrapEvaluateResult(await page.evaluate(`(${findMessagingApiUrl.toString()})()`));
+    if (located && located.loginRequired) {
+      throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn requires an active signed-in browser session.');
+    }
+    if (!located || !located.url) {
+      await page.wait(6);
+      located = unwrapEvaluateResult(await page.evaluate(`(${findMessagingApiUrl.toString()})()`));
+    }
+    if (!located || !located.url) {
+      throw new CommandExecutionError(
+        'LinkedIn did not issue a messaging API request; the inbox may have failed to load.',
+      );
+    }
+
+    const cookies = await page.getCookies({ url: 'https://www.linkedin.com' });
+    const jsession = cookies.find((c) => c.name === 'JSESSIONID')?.value;
+    if (!jsession) {
+      throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn.');
+    }
+    const csrf = jsession.replace(/^"|"$/g, '');
+
+    // Widen the page size to the requested limit where the query supports it.
+    const targetUrl = located.url.replace(/count:\d+/, 'count:' + limit);
+    const fetched = unwrapEvaluateResult(
+      await page.evaluate(`(${fetchMessagingApi.toString()})(${JSON.stringify(targetUrl)}, ${JSON.stringify(csrf)})`),
+    );
+    if (fetched && fetched.authRequired) {
+      throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn messaging API authentication failed: ' + fetched.error);
+    }
+    if (!fetched || fetched.error || !fetched.json) {
+      throw new CommandExecutionError(
+        'LinkedIn messaging API returned an unexpected response: ' + ((fetched && fetched.error) || 'no data'),
+      );
+    }
+
+    let conversations = parseConversations(fetched.json, located.mailboxUrn || '');
+    if (unreadOnly) conversations = conversations.filter((c) => c.unread);
+    if (conversations.length === 0) {
+      if (unreadOnly) return [];
+      throw new EmptyResultError('linkedin inbox', 'No LinkedIn conversations were found in the inbox.');
+    }
+
+    return conversations.slice(0, limit).map((c, index) => ({
+      rank: index + 1,
+      thread_url: threadUrl(c.thread_id),
+      thread_id: c.thread_id,
+      person_name: c.person_name,
+      last_message_preview: c.last_message_preview,
+      unread: c.unread,
+      counterparty_type: c.counterparty_type,
+      category: c.category,
+      timestamp: c.timestamp,
+    }));
+  },
+});
+
+export const __test__ = {
+  parseConversations,
+  threadUrl,
+};

package/clis/linkedin/inbox.test.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import './inbox.js';
+
+const { parseConversations, threadUrl } = await import('./inbox.js').then((m) => m.__test__);
+
+const SELF = 'urn:li:fsd_profile:SELF';
+
+// Minimal normalized messaging payload mirroring LinkedIn's real response shape:
+// a flat `included` entity array where conversations reference participants and
+// messages by URN.
+function fixture() {
+  return {
+    included: [
+      {
+        $type: 'com.linkedin.messenger.MessagingParticipant',
+        entityUrn: 'urn:li:msg_messagingParticipant:SELF',
+        hostIdentityUrn: SELF,
+        participantType: { member: { firstName: { text: 'Hanzi' }, lastName: { text: 'Li' } } },
+      },
+      {
+        $type: 'com.linkedin.messenger.MessagingParticipant',
+        entityUrn: 'urn:li:msg_messagingParticipant:P1',
+        hostIdentityUrn: 'urn:li:fsd_profile:P1',
+        participantType: { member: { firstName: { text: 'Olga' }, lastName: { text: 'Magere' } } },
+      },
+      {
+        $type: 'com.linkedin.messenger.MessagingParticipant',
+        entityUrn: 'urn:li:msg_messagingParticipant:ORG',
+        hostIdentityUrn: 'urn:li:fsd_company:99',
+        participantType: { organization: { name: { text: 'American Express' } } },
+      },
+      { $type: 'com.linkedin.messenger.Message', entityUrn: 'urn:li:msg_message:M1', body: { text: 'hey, are you around   this week?' } },
+      { $type: 'com.linkedin.messenger.Message', entityUrn: 'urn:li:msg_message:M2', body: { text: 'Sponsored offer' } },
+      {
+        $type: 'com.linkedin.messenger.Conversation',
+        entityUrn: 'urn:li:msg_conversation:C1',
+        backendUrn: 'urn:li:messagingThread:2-aaa==',
+        unreadCount: 2,
+        read: false,
+        categories: ['INBOX', 'PRIMARY_INBOX'],
+        lastActivityAt: 2000,
+        '*conversationParticipants': ['urn:li:msg_messagingParticipant:P1', 'urn:li:msg_messagingParticipant:SELF'],
+        messages: { '*elements': ['urn:li:msg_message:M1'] },
+        title: null,
+      },
+      {
+        $type: 'com.linkedin.messenger.Conversation',
+        entityUrn: 'urn:li:msg_conversation:C2',
+        backendUrn: 'urn:li:messagingThread:2-bbb==',
+        unreadCount: 0,
+        read: true,
+        categories: ['INBOX', 'PRIMARY_INBOX', 'INMAIL'],
+        lastActivityAt: 3000,
+        '*conversationParticipants': ['urn:li:msg_messagingParticipant:ORG', 'urn:li:msg_messagingParticipant:SELF'],
+        messages: { '*elements': ['urn:li:msg_message:M2'] },
+        title: null,
+      },
+      {
+        $type: 'com.linkedin.messenger.Conversation',
+        entityUrn: 'urn:li:msg_conversation:C3',
+        backendUrn: 'urn:li:messagingThread:2-ccc==',
+        unreadCount: 0,
+        read: true,
+        categories: ['INBOX', 'PRIMARY_INBOX'],
+        lastActivityAt: 1000,
+        '*conversationParticipants': ['urn:li:msg_messagingParticipant:P1', 'urn:li:msg_messagingParticipant:SELF'],
+        messages: { '*elements': [] },
+        title: 'Cohort 2 group',
+      },
+    ],
+  };
+}
+
+describe('linkedin inbox adapter', () => {
+  const command = getRegistry().get('linkedin/inbox');
+
+  it('registers the command with the expected shape', () => {
+    expect(command).toBeDefined();
+    expect(command.site).toBe('linkedin');
+    expect(command.name).toBe('inbox');
+    expect(command.domain).toBe('www.linkedin.com');
+    expect(command.strategy).toBe('cookie');
+    expect(command.browser).toBe(true);
+    expect(typeof command.func).toBe('function');
+  });
+
+  it('exposes channel-safe structured columns', () => {
+    expect(command.columns).toEqual(
+      expect.arrayContaining([
+        'thread_url',
+        'thread_id',
+        'person_name',
+        'last_message_preview',
+        'unread',
+        'counterparty_type',
+        'category',
+        'timestamp',
+      ]),
+    );
+  });
+
+  it('builds a thread URL from a thread id', () => {
+    expect(threadUrl('2-aaa==')).toBe('https://www.linkedin.com/messaging/thread/2-aaa==/');
+    expect(threadUrl('')).toBe('');
+  });
+
+  it('parses conversations and sorts them by most recent activity', () => {
+    const rows = parseConversations(fixture(), SELF);
+    expect(rows).toHaveLength(3);
+    expect(rows.map((r) => r.thread_id)).toEqual(['2-bbb==', '2-aaa==', '2-ccc==']);
+  });
+
+  it('resolves the member counterparty, excludes the inbox owner, and reports unread state', () => {
+    const c1 = parseConversations(fixture(), SELF).find((r) => r.thread_id === '2-aaa==');
+    expect(c1.person_name).toBe('Olga Magere');
+    expect(c1.counterparty_type).toBe('member');
+    expect(c1.unread).toBe(true);
+    expect(c1.last_message_preview).toBe('hey, are you around this week?');
+  });
+
+  it('flags organization counterparties and read conversations', () => {
+    const c2 = parseConversations(fixture(), SELF).find((r) => r.thread_id === '2-bbb==');
+    expect(c2.person_name).toBe('American Express');
+    expect(c2.counterparty_type).toBe('organization');
+    expect(c2.unread).toBe(false);
+    expect(c2.category).toBe('INBOX,PRIMARY_INBOX,INMAIL');
+  });
+
+  it('uses the group title as the conversation name', () => {
+    const c3 = parseConversations(fixture(), SELF).find((r) => r.thread_id === '2-ccc==');
+    expect(c3.person_name).toBe('Cohort 2 group');
+  });
+
+  it('returns an empty array when a valid payload has no conversations', () => {
+    expect(parseConversations({ included: [] }, SELF)).toEqual([]);
+  });
+
+  it('fails typed when the normalized payload shape is malformed', () => {
+    expect(() => parseConversations({}, SELF)).toThrow(CommandExecutionError);
+    expect(() => parseConversations(null, SELF)).toThrow(CommandExecutionError);
+    const malformed = fixture();
+    malformed.included.push({
+      $type: 'com.linkedin.messenger.Conversation',
+      entityUrn: 'urn:li:msg_conversation:MALFORMED',
+      '*conversationParticipants': [],
+      messages: { '*elements': [] },
+    });
+    expect(() => parseConversations(malformed, SELF)).toThrow(CommandExecutionError);
+  });
+});