@jackwener/opencli 1.7.22 → 1.8.1

package/clis/linkedin/safe-send.test.js

@@ -0,0 +1,204 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import './safe-send.js';
+
+const {
+  normalizeWhitespace,
+  normalizeName,
+  canonicalizeLinkedInThreadUrl,
+  hashText,
+  assessThreadSafety,
+} = await import('./safe-send.js').then((m) => m.__test__);
+
+function makeFakePage(probe) {
+  let composerText = probe.composerText || '';
+  return {
+    goto: vi.fn(async () => undefined),
+    wait: vi.fn(async () => undefined),
+    evaluate: vi.fn(async (script) => {
+      const text = String(script);
+      if (text.includes('__OPENCLI_LINKEDIN_PROBE__')) return probe;
+      if (text.includes('__OPENCLI_LINKEDIN_FOCUS_COMPOSER__')) return { ok: true, composerText: '' };
+      if (text.includes('__OPENCLI_LINKEDIN_READ_COMPOSER__')) return { ok: true, composerText };
+      if (text.includes('__OPENCLI_LINKEDIN_CLICK_SEND__')) return { ok: true, sent: true };
+      return undefined;
+    }),
+    insertText: vi.fn(async (text) => {
+      composerText = text;
+    }),
+    pressKey: vi.fn(async () => undefined),
+    screenshot: vi.fn(async () => 'base64-screenshot'),
+  };
+}
+
+describe('linkedin safe-send helpers', () => {
+  it('normalizes whitespace and LinkedIn names for exact-ish comparisons', () => {
+    expect(normalizeWhitespace('  Lokesh\n\tRamesh  ')).toBe('Lokesh Ramesh');
+    expect(normalizeName('Lokesh Ramesh • 1st')).toBe('lokesh ramesh');
+  });
+
+  it('canonicalizes thread URLs while dropping query and hash noise', () => {
+    expect(canonicalizeLinkedInThreadUrl('https://www.linkedin.com/messaging/thread/abc/?foo=1#bar'))
+      .toBe('https://www.linkedin.com/messaging/thread/abc/');
+    expect(canonicalizeLinkedInThreadUrl('https://www.linkedin.com/messaging/thread/abc/extra')).toBe('');
+    expect(canonicalizeLinkedInThreadUrl('https://evil-linkedin.com/messaging/thread/abc/')).toBe('');
+    expect(canonicalizeLinkedInThreadUrl('http://www.linkedin.com/messaging/thread/abc/')).toBe('');
+  });
+
+  it('fails closed when LinkedIn search produced no results even if a composer is visible', () => {
+    const result = assessThreadSafety({
+      url: 'https://www.linkedin.com/messaging/thread/bora/',
+      headerNames: ['Bora Nicholson'],
+      bodyText: "We didn't find anything for Victoria Munoz\nBora Nicholson",
+      searchFailure: true,
+      composerFound: true,
+      latestMessageHash: hashText('hello'),
+    }, {
+      expectedName: 'Victoria Munoz',
+      threadUrl: 'https://www.linkedin.com/messaging/thread/victoria/',
+      expectedLastText: 'hello',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.blockReason).toBe('search_failure_visible');
+  });
+
+  it('fails closed on recipient header mismatch', () => {
+    const result = assessThreadSafety({
+      url: 'https://www.linkedin.com/messaging/thread/bora/',
+      headerNames: ['Bora Nicholson'],
+      bodyText: 'Bora Nicholson\nhello',
+      composerFound: true,
+      latestMessageHash: hashText('hello'),
+    }, {
+      expectedName: 'Victoria Munoz',
+      expectedLastText: 'hello',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.blockReason).toBe('recipient_header_mismatch');
+    expect(result.actualValue).toBe('Bora Nicholson');
+  });
+
+  it('fails closed when the stored latest message is no longer visible', () => {
+    const result = assessThreadSafety({
+      url: 'https://www.linkedin.com/messaging/thread/lokesh/',
+      headerNames: ['Lokesh Ramesh'],
+      bodyText: 'Lokesh Ramesh\na newer inbound arrived',
+      composerFound: true,
+      latestMessageHash: hashText('a newer inbound arrived'),
+    }, {
+      expectedName: 'Lokesh Ramesh',
+      expectedLastText: 'old inbound text',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.blockReason).toBe('latest_message_mismatch');
+  });
+
+  it('passes only when recipient, thread, latest text, and composer are all verified', () => {
+    const result = assessThreadSafety({
+      url: 'https://www.linkedin.com/messaging/thread/lokesh/?mini=true',
+      headerNames: ['Lokesh Ramesh'],
+      bodyText: 'Lokesh Ramesh\nI think outside help would fit best for provider doc follow ups',
+      composerFound: true,
+      latestMessageHash: hashText('I think outside help would fit best for provider doc follow ups'),
+    }, {
+      expectedName: 'Lokesh Ramesh',
+      threadUrl: 'https://www.linkedin.com/messaging/thread/lokesh/',
+      expectedLastText: 'provider doc follow ups',
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.blockReason).toBe('verified');
+  });
+});
+
+describe('linkedin safe-send command', () => {
+  it('registers as a write command with safe output columns', () => {
+    const command = getRegistry().get('linkedin/safe-send');
+    expect(command).toBeDefined();
+    expect(command.access).toBe('write');
+    expect(command.columns).toEqual(expect.arrayContaining(['status', 'recipient', 'reason']));
+  });
+
+  it('does not type or send when verification fails', async () => {
+    const command = getRegistry().get('linkedin/safe-send');
+    const page = makeFakePage({
+      url: 'https://www.linkedin.com/messaging/thread/bora/',
+      headerNames: ['Bora Nicholson'],
+      bodyText: 'Bora Nicholson',
+      composerFound: true,
+      searchFailure: false,
+    });
+
+    await expect(command.func(page, {
+      'thread-url': 'https://www.linkedin.com/messaging/thread/victoria/',
+      'expected-name': 'Victoria Munoz',
+      message: 'hello victoria',
+      send: true,
+    })).rejects.toBeInstanceOf(CommandExecutionError);
+
+    expect(page.insertText).not.toHaveBeenCalled();
+    expect(page.pressKey).not.toHaveBeenCalled();
+  });
+
+  it('rejects non-thread URLs before navigating or typing', async () => {
+    const command = getRegistry().get('linkedin/safe-send');
+    const page = makeFakePage({});
+
+    await expect(command.func(page, {
+      'thread-url': 'https://www.linkedin.com/feed/',
+      'expected-name': 'Victoria Munoz',
+      message: 'hello victoria',
+      send: true,
+    })).rejects.toBeInstanceOf(ArgumentError);
+
+    expect(page.goto).not.toHaveBeenCalled();
+    expect(page.insertText).not.toHaveBeenCalled();
+  });
+
+  it('dry-runs by default after verification without filling or sending', async () => {
+    const command = getRegistry().get('linkedin/safe-send');
+    const page = makeFakePage({
+      url: 'https://www.linkedin.com/messaging/thread/lokesh/',
+      headerNames: ['Lokesh Ramesh'],
+      bodyText: 'Lokesh Ramesh\nprovider doc follow ups',
+      composerFound: true,
+      searchFailure: false,
+    });
+
+    const rows = await command.func(page, {
+      'thread-url': 'https://www.linkedin.com/messaging/thread/lokesh/',
+      'expected-name': 'Lokesh Ramesh',
+      message: 'both, but starting hands on',
+    });
+
+    expect(rows[0]).toMatchObject({ status: 'verified_dry_run', recipient: 'Lokesh Ramesh', reason: 'verified' });
+    expect(page.insertText).not.toHaveBeenCalled();
+    expect(page.pressKey).not.toHaveBeenCalled();
+  });
+
+  it('fills and sends only when --send is explicitly true and post-fill verification matches exactly', async () => {
+    const command = getRegistry().get('linkedin/safe-send');
+    const page = makeFakePage({
+      url: 'https://www.linkedin.com/messaging/thread/lokesh/',
+      headerNames: ['Lokesh Ramesh'],
+      bodyText: 'Lokesh Ramesh\nprovider doc follow ups',
+      composerFound: true,
+      searchFailure: false,
+    });
+
+    const rows = await command.func(page, {
+      'thread-url': 'https://www.linkedin.com/messaging/thread/lokesh/',
+      'expected-name': 'Lokesh Ramesh',
+      message: 'both, but starting hands on',
+      send: true,
+    });
+
+    expect(rows[0]).toMatchObject({ status: 'sent', recipient: 'Lokesh Ramesh', reason: 'verified' });
+    expect(page.insertText).toHaveBeenCalledWith('both, but starting hands on');
+    expect(page.pressKey).not.toHaveBeenCalled();
+  });
+});

package/clis/linkedin/salesnav-inbox.js

@@ -0,0 +1,210 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const LINKEDIN_DOMAIN = 'www.linkedin.com';
+const SALES_INBOX_URL = 'https://www.linkedin.com/sales/inbox/';
+const THREADS_BASE = 'https://www.linkedin.com/sales-api/salesApiMessagingThreads';
+const PAGE_SIZE = 20;
+const DEFAULT_LIMIT = 40;
+const MAX_LIMIT = 500;
+const THREAD_DECORATION = '(id,restrictions,archived,unreadMessageCount,nextPageStartsAt,totalMessageCount,messages*(id,type,contentFlag,deliveredAt,lastEditedAt,subject,body,footerText,blockCopy,attachments,author,systemMessageContent),participants*~fs_salesProfile(entityUrn,firstName,lastName,fullName,degree,profilePictureDisplayImage,objectUrn,inmailRestriction))';
+
+export function normalizeWhitespace(value) {
+  return String(value ?? '').replace(/[\u00a0\u202f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+export function parseLimit(value, defaultValue = DEFAULT_LIMIT) {
+  if (value === undefined || value === null || value === '') return defaultValue;
+  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;
+}
+
+export function encodeRestliDecoration(value) {
+  // LinkedIn's Sales Navigator Rest.li endpoint returns HTTP 400 when this
+  // decoration is sent with literal parentheses. Keep parentheses percent-encoded.
+  return encodeURIComponent(value).replace(/\(/g, '%28').replace(/\)/g, '%29');
+}
+
+function salesnavThreadUrl(threadId) {
+  return threadId ? `https://www.linkedin.com/sales/inbox/${encodeURIComponent(threadId)}` : '';
+}
+
+function threadListUrl({ count = PAGE_SIZE, pageStartsAt = '' } = {}) {
+  let url = `${THREADS_BASE}?decoration=${encodeRestliDecoration(THREAD_DECORATION)}&count=${count}&filter=INBOX&q=filter`;
+  if (pageStartsAt) url += `&pageStartsAt=${encodeURIComponent(pageStartsAt)}`;
+  return url;
+}
+
+function getThreadParticipants(thread) {
+  const resolution = thread?.participantsResolutionResults || {};
+  const participants = Array.isArray(thread?.participants) ? thread.participants : Object.keys(resolution);
+  return participants.map((urn) => resolution[urn] || { entityUrn: urn }).filter(Boolean);
+}
+
+function isSelfParticipant(profile) {
+  const degree = String(profile?.degree ?? '').trim();
+  return degree === '0';
+}
+
+function otherParticipantName(thread) {
+  const participants = getThreadParticipants(thread);
+  const other = participants.find((p) => !isSelfParticipant(p)) || participants[0];
+  return normalizeWhitespace(other?.fullName || [other?.firstName, other?.lastName].filter(Boolean).join(' '));
+}
+
+function parseSalesnavThreads(json) {
+  if (!json || typeof json !== 'object' || !Array.isArray(json.elements)) {
+    throw new CommandExecutionError('Sales Navigator messaging threads API returned malformed payload');
+  }
+  return json.elements.map((thread) => {
+    if (!thread || typeof thread !== 'object') {
+      throw new CommandExecutionError('Sales Navigator messaging threads API returned malformed thread row');
+    }
+    const messages = Array.isArray(thread?.messages) ? thread.messages : [];
+    const lastMessage = messages[0] || {};
+    const deliveredAt = Number(lastMessage.deliveredAt || thread?.nextPageStartsAt || 0);
+    const threadId = normalizeWhitespace(thread?.id || '');
+    if (!threadId) {
+      throw new CommandExecutionError('Sales Navigator messaging thread row missing id');
+    }
+    return {
+      thread_id: threadId,
+      thread_url: salesnavThreadUrl(threadId),
+      person_name: otherParticipantName(thread),
+      last_message_snippet: normalizeWhitespace(lastMessage.body || lastMessage.subject || '').slice(0, 300),
+      last_activity_time: deliveredAt ? new Date(deliveredAt).toISOString() : '',
+      unread: Number(thread?.unreadMessageCount || 0) > 0,
+      unread_count: Number(thread?.unreadMessageCount || 0),
+      total_message_count: Number(thread?.totalMessageCount || messages.length || 0),
+      archived: Boolean(thread?.archived),
+      next_page_starts_at: normalizeWhitespace(thread?.nextPageStartsAt || ''),
+      participants: getThreadParticipants(thread).map((p) => ({
+        name: normalizeWhitespace(p.fullName || [p.firstName, p.lastName].filter(Boolean).join(' ')),
+        entity_urn: normalizeWhitespace(p.entityUrn || ''),
+        object_urn: normalizeWhitespace(p.objectUrn || ''),
+        degree: normalizeWhitespace(p.degree ?? ''),
+      })),
+    };
+  });
+}
+
+function fetchJsonScript(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',
+        },
+      });
+      const text = await res.text();
+      let json = null;
+      try { json = text ? JSON.parse(text) : null; } catch (_) { json = null; }
+      if (res.status === 401 || res.status === 403) return { authRequired: true, status: res.status, text };
+      if (!res.ok) return { error: 'HTTP ' + res.status, status: res.status, text, json };
+      return { status: res.status, json };
+    } catch (e) {
+      return { error: 'fetch failed: ' + ((e && e.message) || String(e)) };
+    }
+  })()`;
+}
+
+export async function getCsrf(page) {
+  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.');
+  return jsession.replace(/^\"|\"$/g, '');
+}
+
+export async function fetchSalesnavJson(page, csrf, url, label) {
+  const result = unwrapEvaluateResult(await page.evaluate(fetchJsonScript(url, csrf)));
+  if (result?.authRequired) throw new AuthRequiredError(LINKEDIN_DOMAIN, `${label} authentication failed (HTTP ${result.status || 'auth_required'}).`);
+  if (result?.error || !result?.json) throw new CommandExecutionError(`${label} returned an unexpected response`, `${result?.error || 'no_json'}\n${normalizeWhitespace(result?.text || '').slice(0, 500)}`);
+  return result.json;
+}
+
+export async function fetchInboxRows(page, { limit = DEFAULT_LIMIT, maxPages = 30 } = {}) {
+  const csrf = await getCsrf(page);
+  const rows = [];
+  const seen = new Set();
+  let pageStartsAt = '';
+  let pagesFetched = 0;
+  let hasMorePages = false;
+  while (rows.length < limit && pagesFetched < maxPages) {
+    const json = await fetchSalesnavJson(page, csrf, threadListUrl({ count: PAGE_SIZE, pageStartsAt }), 'Sales Navigator messaging threads API');
+    pagesFetched += 1;
+    const pageRows = parseSalesnavThreads(json);
+    if (pageRows.length === 0) break;
+    for (const row of pageRows) {
+      if (seen.has(row.thread_id)) continue;
+      seen.add(row.thread_id);
+      rows.push(row);
+      if (rows.length >= limit) break;
+    }
+    const last = pageRows[pageRows.length - 1];
+    const next = last?.next_page_starts_at;
+    hasMorePages = Boolean(next);
+    if (!next) break;
+    if (next === pageStartsAt) {
+      throw new CommandExecutionError('Sales Navigator messaging threads API returned the same cursor twice');
+    }
+    pageStartsAt = next;
+  }
+  if (rows.length < limit && hasMorePages && pagesFetched >= maxPages) {
+    throw new CommandExecutionError(`Sales Navigator messaging threads API reached the ${maxPages}-page safety cap before collecting ${limit} conversations`);
+  }
+  return rows.slice(0, limit).map((row, index) => ({ ...row, rank: index + 1 }));
+}
+
+export { THREAD_DECORATION, THREADS_BASE };
+
+cli({
+  site: 'linkedin',
+  name: 'salesnav-inbox',
+  access: 'read',
+  description: 'List LinkedIn Sales Navigator message conversations with API pagination',
+  domain: LINKEDIN_DOMAIN,
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'limit', type: 'number', default: DEFAULT_LIMIT, help: 'Maximum conversations to return (1-500)' },
+    { name: 'max-pages', type: 'number', default: 30, help: 'Maximum Sales Navigator API pages to fetch' },
+    { name: 'unread-only', type: 'bool', default: false, help: 'Return only unread conversations' },
+  ],
+  columns: ['rank', 'thread_id', 'thread_url', 'person_name', 'last_message_snippet', 'last_activity_time', 'unread', 'unread_count', 'total_message_count', 'archived', 'participants', 'next_page_starts_at'],
+  func: async (page, args) => {
+    if (!page) throw new CommandExecutionError('Browser session required for linkedin salesnav-inbox');
+    const limit = parseLimit(args.limit);
+    const maxPages = parseLimit(args['max-pages'], 30);
+    await page.goto(SALES_INBOX_URL);
+    await page.wait(4);
+    let rows = await fetchInboxRows(page, { limit, maxPages });
+    if (args['unread-only']) rows = rows.filter((row) => row.unread);
+    if (rows.length === 0) {
+      if (args['unread-only']) return [];
+      throw new EmptyResultError('linkedin salesnav-inbox', 'No Sales Navigator conversations were found.');
+    }
+    return rows.slice(0, limit).map((row, index) => ({ ...row, rank: index + 1 }));
+  },
+});
+
+export const __test__ = {
+  THREAD_DECORATION,
+  normalizeWhitespace,
+  parseLimit,
+  encodeRestliDecoration,
+  salesnavThreadUrl,
+  threadListUrl,
+  parseSalesnavThreads,
+  fetchInboxRows,
+};

package/clis/linkedin/salesnav-inbox.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import './salesnav-inbox.js';
+
+const {
+  THREAD_DECORATION,
+  encodeRestliDecoration,
+  parseLimit,
+  parseSalesnavThreads,
+  salesnavThreadUrl,
+  threadListUrl,
+} = await import('./salesnav-inbox.js').then((m) => m.__test__);
+
+describe('linkedin salesnav-inbox command', () => {
+  it('percent-encodes Rest.li decoration parentheses for Sales Navigator messaging', () => {
+    const encoded = encodeRestliDecoration('(id,messages*(body))');
+    expect(encoded).toBe('%28id%2Cmessages*%28body%29%29');
+    expect(encoded).not.toContain('(');
+    expect(encoded).not.toContain(')');
+  });
+
+  it('builds the paginated salesApiMessagingThreads inbox URL', () => {
+    const url = threadListUrl({ count: 20, pageStartsAt: '1779070755626' });
+    expect(url).toContain('/sales-api/salesApiMessagingThreads?');
+    expect(url).toContain('q=filter');
+    expect(url).toContain('filter=INBOX');
+    expect(url).toContain('count=20');
+    expect(url).toContain('pageStartsAt=1779070755626');
+    expect(url).toContain(encodeRestliDecoration(THREAD_DECORATION));
+  });
+
+  it('validates limits without silent clamping', () => {
+    expect(parseLimit(undefined)).toBe(40);
+    expect(parseLimit(12)).toBe(12);
+    expect(() => parseLimit(0)).toThrow();
+    expect(() => parseLimit(501)).toThrow();
+    expect(() => parseLimit('abc')).toThrow();
+  });
+
+  it('parses Sales Navigator thread rows with other participant and unread state', () => {
+    const rows = parseSalesnavThreads({ elements: [{
+      id: '2-thread',
+      unreadMessageCount: 1,
+      archived: false,
+      totalMessageCount: 2,
+      nextPageStartsAt: 1778206803669,
+      participants: [
+        'urn:li:fs_salesProfile:(OTHER,NAME_SEARCH,T1)',
+        'urn:li:fs_salesProfile:(SELF,NAME_SEARCH,T2)',
+      ],
+      participantsResolutionResults: {
+        'urn:li:fs_salesProfile:(OTHER,NAME_SEARCH,T1)': {
+          entityUrn: 'urn:li:fs_salesProfile:(OTHER,NAME_SEARCH,T1)',
+          firstName: 'Rachael',
+          lastName: 'Stolberg',
+          fullName: 'Rachael Stolberg',
+          degree: 2,
+        },
+        'urn:li:fs_salesProfile:(SELF,NAME_SEARCH,T2)': {
+          entityUrn: 'urn:li:fs_salesProfile:(SELF,NAME_SEARCH,T2)',
+          firstName: 'Hanzi',
+          lastName: 'Li',
+          fullName: 'Hanzi Li',
+          degree: 0,
+        },
+      },
+      messages: [{
+        id: 'msg-1',
+        author: 'urn:li:fs_salesProfile:(OTHER,NAME_SEARCH,T1)',
+        body: 'Hi hanzi, happy to chat',
+        deliveredAt: 1778206803669,
+      }],
+    }] });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      thread_id: '2-thread',
+      thread_url: salesnavThreadUrl('2-thread'),
+      person_name: 'Rachael Stolberg',
+      last_message_snippet: 'Hi hanzi, happy to chat',
+      last_activity_time: '2026-05-08T02:20:03.669Z',
+      unread: true,
+      unread_count: 1,
+      total_message_count: 2,
+    });
+  });
+
+  it('does not hard-code a specific account name as the inbox owner', () => {
+    const rows = parseSalesnavThreads({ elements: [{
+      id: '2-thread',
+      participants: [
+        'urn:li:fs_salesProfile:(HANZI,NAME_SEARCH,T1)',
+        'urn:li:fs_salesProfile:(ME,NAME_SEARCH,T2)',
+      ],
+      participantsResolutionResults: {
+        'urn:li:fs_salesProfile:(HANZI,NAME_SEARCH,T1)': {
+          fullName: 'Hanzi Li',
+          degree: 2,
+        },
+        'urn:li:fs_salesProfile:(ME,NAME_SEARCH,T2)': {
+          fullName: 'Current User',
+          degree: 0,
+        },
+      },
+      messages: [],
+    }] });
+    expect(rows[0].person_name).toBe('Hanzi Li');
+  });
+
+  it('fails typed on malformed thread payloads and missing thread identity', () => {
+    expect(() => parseSalesnavThreads({})).toThrow(CommandExecutionError);
+    expect(() => parseSalesnavThreads({ elements: [{}] })).toThrow(CommandExecutionError);
+  });
+});