@zenalexa/unicli 0.219.0 → 0.220.1

package/src/adapters/indeed/jobs.ts

@@ -0,0 +1,375 @@
+/**
+ * @owner   src/adapters/indeed/jobs.ts
+ * @does    Register agent-facing Indeed search and job-detail browser commands.
+ * @needs   Logged-in or challenge-cleared indeed.com browser session and stable rendered job DOM.
+ * @feeds   surface coverage ledger and job-search research workflows.
+ * @breaks  Indeed Cloudflare challenge changes, search-card DOM drift, or job-detail selector changes.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+
+const INDEED_ORIGIN = "https://www.indeed.com";
+const JK_PATTERN = /^[a-f0-9]{16}$/;
+const FROMAGE_VALUES = new Set(["1", "3", "7", "14"]);
+const SORT_VALUES = new Set(["relevance", "date"]);
+
+export const INDEED_SEARCH_COLUMNS = [
+  "rank",
+  "id",
+  "title",
+  "company",
+  "location",
+  "salary",
+  "tags",
+  "url",
+];
+
+export const INDEED_JOB_COLUMNS = [
+  "id",
+  "title",
+  "company",
+  "location",
+  "salary",
+  "job_type",
+  "description",
+  "url",
+];
+
+interface IndeedSearchCard {
+  jk?: unknown;
+  title?: unknown;
+  company?: unknown;
+  location?: unknown;
+  salary?: unknown;
+  tags?: unknown;
+}
+
+interface IndeedSearchResult {
+  cards?: unknown;
+  challenge?: unknown;
+  ready?: unknown;
+}
+
+interface IndeedJobResult {
+  ready?: unknown;
+  challenge?: unknown;
+  notFound?: unknown;
+  title?: unknown;
+  company?: unknown;
+  location?: unknown;
+  salary?: unknown;
+  jobType?: unknown;
+  description?: unknown;
+}
+
+export function coerceIndeedInt(value: unknown): number {
+  if (value === undefined || value === null || value === "") return Number.NaN;
+  const numberValue = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(numberValue) && Number.isInteger(numberValue)
+    ? numberValue
+    : Number.NaN;
+}
+
+export function requireIndeedBoundedInt(
+  value: unknown,
+  defaultValue: number,
+  maxValue: number,
+  label: string,
+): number {
+  const numberValue = coerceIndeedInt(value ?? defaultValue);
+  if (!Number.isInteger(numberValue) || numberValue <= 0) {
+    throw new Error(`indeed ${label} must be a positive integer.`);
+  }
+  if (numberValue > maxValue) {
+    throw new Error(`indeed ${label} must be <= ${maxValue}.`);
+  }
+  return numberValue;
+}
+
+export function requireIndeedNonNegativeInt(
+  value: unknown,
+  defaultValue: number,
+  label: string,
+): number {
+  const numberValue = coerceIndeedInt(value ?? defaultValue);
+  if (!Number.isInteger(numberValue) || numberValue < 0) {
+    throw new Error(`indeed ${label} must be a non-negative integer.`);
+  }
+  return numberValue;
+}
+
+export function requireIndeedJobKey(value: unknown): string {
+  const id = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!id) throw new Error("indeed job id is required.");
+  if (!JK_PATTERN.test(id)) {
+    throw new Error(
+      `indeed job id "${String(value)}" is not a valid jk; expected 16-char hex.`,
+    );
+  }
+  return id;
+}
+
+export function requireIndeedQuery(value: unknown): string {
+  const query = String(value ?? "").trim();
+  if (!query) throw new Error("indeed query cannot be empty.");
+  return query;
+}
+
+export function requireIndeedFromage(value: unknown): string {
+  if (value === undefined || value === null || value === "") return "";
+  const fromage = String(value).trim();
+  if (!FROMAGE_VALUES.has(fromage)) {
+    throw new Error(
+      `indeed fromage must be one of 1/3/7/14 days, got "${String(value)}".`,
+    );
+  }
+  return fromage;
+}
+
+export function requireIndeedSort(value: unknown): string {
+  const sort = String(value ?? "relevance")
+    .trim()
+    .toLowerCase();
+  if (!SORT_VALUES.has(sort)) {
+    throw new Error(`indeed sort must be "relevance" or "date".`);
+  }
+  return sort;
+}
+
+export function buildIndeedSearchUrl(config: {
+  query: string;
+  location: string;
+  fromage: string;
+  sort: string;
+  start: number;
+}): string {
+  const params = new URLSearchParams();
+  params.set("q", config.query);
+  if (config.location) params.set("l", config.location);
+  if (config.fromage) params.set("fromage", config.fromage);
+  if (config.sort && config.sort !== "relevance") {
+    params.set("sort", config.sort);
+  }
+  if (config.start > 0) params.set("start", String(config.start));
+  return `${INDEED_ORIGIN}/jobs?${params.toString()}`;
+}
+
+export function buildIndeedJobUrl(jk: string): string {
+  return `${INDEED_ORIGIN}/viewjob?jk=${jk}`;
+}
+
+export function dedupeIndeedTags(tags: unknown, salary: string): string {
+  if (!Array.isArray(tags)) return "";
+  const seen: string[] = [];
+  for (const tag of tags) {
+    const text = String(tag ?? "").trim();
+    if (!text || text === salary || seen.includes(text)) continue;
+    seen.push(text);
+  }
+  return seen.join(" · ");
+}
+
+export function indeedSearchCardToRow(
+  card: IndeedSearchCard,
+  rank: number,
+): Record<string, unknown> {
+  const jk = String(card?.jk ?? "").trim();
+  const salary = String(card?.salary ?? "").trim();
+  return {
+    rank,
+    id: jk,
+    title: String(card?.title ?? "")
+      .replace(/\s+/g, " ")
+      .trim(),
+    company: String(card?.company ?? "")
+      .replace(/\s+/g, " ")
+      .trim(),
+    location: String(card?.location ?? "")
+      .replace(/\s+/g, " ")
+      .trim(),
+    salary,
+    tags: dedupeIndeedTags(card?.tags, salary),
+    url: jk ? buildIndeedJobUrl(jk) : "",
+  };
+}
+
+export function buildIndeedSearchExtractScript(): string {
+  return `(async () => {
+    const hasResults = () => Boolean(document.querySelector('.job_seen_beacon'));
+    const hasEmptyState = () => {
+      const text = document.body?.innerText || '';
+      return Boolean(document.querySelector('[data-testid="searchCountPages"], [data-testid="searchCount"], [data-testid="noResultsMessage"], [data-testid="empty-serp-result"]'))
+        || /did not match any jobs|no jobs found|0 jobs/i.test(text);
+    };
+    let ready = hasResults() || hasEmptyState();
+    for (let index = 0; index < 30; index += 1) {
+      if (ready) break;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      ready = hasResults() || hasEmptyState();
+    }
+    const seen = new Set();
+    const cards = [];
+    for (const block of document.querySelectorAll('.job_seen_beacon')) {
+      const titleAnchor = block.querySelector('h2.jobTitle a, [class*="jcs-JobTitle"]');
+      const jk = titleAnchor?.getAttribute('data-jk') || '';
+      if (!jk || seen.has(jk)) continue;
+      seen.add(jk);
+      const tags = Array.from(block.querySelectorAll('.metadataContainer li span'))
+        .map((element) => (element.textContent || '').trim())
+        .filter(Boolean);
+      cards.push({
+        jk,
+        title: block.querySelector('h2.jobTitle span')?.textContent?.trim() || '',
+        company: block.querySelector('[data-testid="company-name"]')?.textContent?.trim() || '',
+        location: block.querySelector('[data-testid="text-location"]')?.textContent?.trim() || '',
+        salary: block.querySelector('.salary-snippet-container span')?.textContent?.trim() || '',
+        tags,
+      });
+    }
+    const challenge = (document.title || '').includes('Just a moment') || Boolean(document.querySelector('[id^="cf-"]'));
+    return { cards, challenge, ready };
+  })()`;
+}
+
+export function buildIndeedJobExtractScript(): string {
+  return `(async () => {
+    let ready = Boolean(document.querySelector('#jobDescriptionText, h1, [data-testid="error-page"]'));
+    for (let index = 0; index < 30; index += 1) {
+      if (ready) break;
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      ready = Boolean(document.querySelector('#jobDescriptionText, h1, [data-testid="error-page"]'));
+    }
+    const challenge = (document.title || '').includes('Just a moment') || Boolean(document.querySelector('[id^="cf-"]'));
+    const headline = document.querySelector('h1')?.textContent || '';
+    const notFound = Boolean(document.querySelector('[data-testid="error-page"]')) || /Page Not Found|not found/i.test(headline);
+    const title = document.querySelector('h1')?.textContent?.trim() || '';
+    const company = document.querySelector('[data-testid="inlineHeader-companyName"] a, [data-testid="inlineHeader-companyName"], [data-company-name="true"]')?.textContent?.trim() || '';
+    const location = document.querySelector('[data-testid="jobsearch-JobInfoHeader-companyLocation"] div, [data-testid="inlineHeader-companyLocation"]')?.textContent?.trim() || '';
+    const salary = document.querySelector('[id*="salaryInfoAndJobType"] span, [data-testid="job-salary"]')?.textContent?.trim() || '';
+    const jobType = Array.from(document.querySelectorAll('[id*="salaryInfoAndJobType"] span, [data-testid="job-type"]'))
+      .map((element) => (element.textContent || '').trim())
+      .filter((text) => text && text !== salary)
+      .join(', ');
+    const description = document.querySelector('#jobDescriptionText')?.innerText?.trim() || '';
+    return { ready, challenge, notFound, title, company, location, salary, jobType, description };
+  })()`;
+}
+
+cli({
+  site: "indeed",
+  name: "search",
+  description: "Search Indeed jobs through the rendered browser DOM",
+  domain: "www.indeed.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "location", type: "str", default: "" },
+    { name: "fromage", type: "str", default: "" },
+    { name: "sort", type: "str", default: "relevance" },
+    { name: "start", type: "int", default: 0 },
+    { name: "limit", type: "int", default: 15 },
+  ],
+  columns: INDEED_SEARCH_COLUMNS,
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const query = requireIndeedQuery(kwargs.query);
+    const location = String(kwargs.location ?? "").trim();
+    const fromage = requireIndeedFromage(kwargs.fromage);
+    const sort = requireIndeedSort(kwargs.sort);
+    const start = requireIndeedNonNegativeInt(kwargs.start, 0, "start");
+    const limit = requireIndeedBoundedInt(kwargs.limit, 15, 25, "limit");
+    const url = buildIndeedSearchUrl({
+      query,
+      location,
+      fromage,
+      sort,
+      start,
+    });
+    await p.goto(url);
+    await p.wait(4);
+    const result = (await p.evaluate(
+      buildIndeedSearchExtractScript(),
+    )) as IndeedSearchResult;
+    if (result?.challenge) {
+      throw new Error(
+        "Indeed served a Cloudflare challenge page. Open indeed.com in the connected browser and clear the challenge, then retry.",
+      );
+    }
+    if (!result?.ready) {
+      throw new Error(
+        "Indeed search page did not expose result or empty-state markers before timeout.",
+      );
+    }
+    const cards = Array.isArray(result?.cards) ? result.cards : [];
+    if (cards.length === 0) {
+      throw new Error(
+        `No Indeed jobs matched "${query}"${location ? ` in ${location}` : ""}.`,
+      );
+    }
+    return cards
+      .slice(0, limit)
+      .map((card, index) =>
+        indeedSearchCardToRow(card as IndeedSearchCard, start + index + 1),
+      );
+  },
+});
+
+cli({
+  site: "indeed",
+  name: "job",
+  description: "Read an Indeed job posting by 16-character jk job key",
+  domain: "www.indeed.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "id", type: "str", required: true, positional: true }],
+  columns: INDEED_JOB_COLUMNS,
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const jk = requireIndeedJobKey(kwargs.id);
+    const url = buildIndeedJobUrl(jk);
+    await p.goto(url);
+    await p.wait(4);
+    const detail = (await p.evaluate(
+      buildIndeedJobExtractScript(),
+    )) as IndeedJobResult;
+    if (detail?.challenge) {
+      throw new Error(
+        "Indeed served a Cloudflare challenge page. Open indeed.com in the connected browser and clear the challenge, then retry.",
+      );
+    }
+    if (!detail?.ready) {
+      throw new Error(
+        "Indeed job page did not expose detail or error markers before timeout.",
+      );
+    }
+    if (detail?.notFound || (!detail?.title && !detail?.description)) {
+      throw new Error(`No Indeed job posting found for jk "${jk}".`);
+    }
+    return [
+      {
+        id: jk,
+        title: String(detail.title ?? "")
+          .replace(/\s+/g, " ")
+          .trim(),
+        company: String(detail.company ?? "")
+          .replace(/\s+/g, " ")
+          .trim(),
+        location: String(detail.location ?? "")
+          .replace(/\s+/g, " ")
+          .trim(),
+        salary: String(detail.salary ?? "")
+          .replace(/\s+/g, " ")
+          .trim(),
+        job_type: String(detail.jobType ?? "")
+          .replace(/\s+/g, " ")
+          .trim(),
+        description: String(detail.description ?? ""),
+        url,
+      },
+    ];
+  },
+});

package/src/adapters/instagram/collections.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { requireInstagramCollectionInput } from "./collections.js";
+
+function pageMock(evaluateResults: unknown[]) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(async () => evaluateResults.shift()),
+  };
+}
+
+describe("instagram collection agent-facing commands", () => {
+  it("validates collection inputs before navigation", async () => {
+    expect(requireInstagramCollectionInput(" Research ", "name")).toBe(
+      "Research",
+    );
+    expect(() => requireInstagramCollectionInput("", "name")).toThrow(
+      "cannot be empty",
+    );
+    const command = resolveCommand("instagram", "collection-create")?.command;
+    const page = pageMock([]);
+    await expect(command!.func!(page, { name: "" })).rejects.toThrow(
+      "cannot be empty",
+    );
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it("creates Instagram saved-post collections", async () => {
+    const command = resolveCommand("instagram", "collection-create")?.command;
+    const page = pageMock([
+      {
+        ok: true,
+        row: {
+          status: "Created",
+          collectionId: "123456",
+          collectionName: "Research",
+          mediaCount: 0,
+        },
+      },
+    ]);
+    await expect(command!.func!(page, { name: "Research" })).resolves.toEqual([
+      {
+        status: "Created",
+        collectionId: "123456",
+        collectionName: "Research",
+        mediaCount: 0,
+      },
+    ]);
+    expect(page.goto).toHaveBeenCalledWith("https://www.instagram.com");
+    expect(String(page.evaluate.mock.calls[0][0])).toContain(
+      "/api/v1/collections/create/",
+    );
+  });
+
+  it("deletes Instagram saved-post collections", async () => {
+    const command = resolveCommand("instagram", "collection-delete")?.command;
+    const page = pageMock([
+      {
+        ok: true,
+        row: {
+          status: "Deleted",
+          collectionId: "123456",
+          collectionName: "Research",
+        },
+      },
+    ]);
+    await expect(command!.func!(page, { target: "Research" })).resolves.toEqual(
+      [
+        {
+          status: "Deleted",
+          collectionId: "123456",
+          collectionName: "Research",
+        },
+      ],
+    );
+    expect(page.goto).toHaveBeenCalledWith("https://www.instagram.com");
+    expect(String(page.evaluate.mock.calls[0][0])).toContain(
+      "/api/v1/collections/list/",
+    );
+    expect(String(page.evaluate.mock.calls[0][0])).toContain(
+      "/api/v1/collections/",
+    );
+  });
+
+  it("propagates Instagram collection API failures", async () => {
+    const command = resolveCommand("instagram", "collection-delete")?.command;
+    const page = pageMock([
+      { ok: false, error: "Collection not found: Research" },
+    ]);
+    await expect(command!.func!(page, { target: "Research" })).rejects.toThrow(
+      "Collection not found",
+    );
+  });
+});

package/src/adapters/instagram/collections.ts

@@ -0,0 +1,206 @@
+/**
+ * @owner   src/adapters/instagram/collections.ts
+ * @does    Register agent-facing Instagram saved collection create and delete commands.
+ * @needs   Logged-in www.instagram.com browser session with csrftoken cookie.
+ * @feeds   surface coverage ledger and saved-post collection management workflows.
+ * @breaks  Instagram private collection API changes, CSRF cookie changes, or collection list schema drift.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+
+interface InstagramCollectionResult {
+  ok?: unknown;
+  error?: unknown;
+  row?: unknown;
+}
+
+interface InstagramCollectionRow {
+  status?: unknown;
+  collectionId?: unknown;
+  collectionName?: unknown;
+  mediaCount?: unknown;
+}
+
+export function requireInstagramCollectionInput(
+  value: unknown,
+  label: string,
+): string {
+  const text = String(value ?? "").trim();
+  if (!text) throw new Error(`Instagram collection ${label} cannot be empty.`);
+  return text;
+}
+
+function buildCreateCollectionScript(name: string): string {
+  return `(async () => {
+    const collectionName = ${JSON.stringify(name)};
+    const csrf = document.cookie.match(/csrftoken=([^;]+)/)?.[1] || '';
+    if (!csrf) return { ok: false, error: 'csrftoken cookie missing; log in to Instagram and retry.' };
+    const form = new FormData();
+    form.append('name', collectionName);
+    form.append('module_name', 'collection_create');
+    const response = await fetch('https://www.instagram.com/api/v1/collections/create/', {
+      method: 'POST',
+      credentials: 'include',
+      headers: {
+        'X-IG-App-ID': '936619743392459',
+        'X-CSRFToken': csrf,
+      },
+      body: form,
+    });
+    const text = await response.text();
+    let data = {};
+    try { data = text ? JSON.parse(text) : {}; } catch {}
+    if (!response.ok) {
+      return { ok: false, error: 'Failed to create collection: HTTP ' + response.status + (text ? ' - ' + text.slice(0, 200) : '') };
+    }
+    if (data?.status && data.status !== 'ok') {
+      return { ok: false, error: 'Instagram returned non-ok status: ' + JSON.stringify(data).slice(0, 300) };
+    }
+    return {
+      ok: true,
+      row: {
+        status: 'Created',
+        collectionId: String(data?.collection_id ?? ''),
+        collectionName: String(data?.collection_name ?? collectionName),
+        mediaCount: data?.collection_media_count ?? 0,
+      },
+    };
+  })()`;
+}
+
+function buildDeleteCollectionScript(target: string): string {
+  return `(async () => {
+    const raw = ${JSON.stringify(target)};
+    const csrf = document.cookie.match(/csrftoken=([^;]+)/)?.[1] || '';
+    if (!csrf) return { ok: false, error: 'csrftoken cookie missing; log in to Instagram and retry.' };
+    const headers = { 'X-IG-App-ID': '936619743392459' };
+    const listResponse = await fetch('https://www.instagram.com/api/v1/collections/list/?collection_types=%5B%22MEDIA%22%5D', {
+      credentials: 'include',
+      headers,
+    });
+    if (!listResponse.ok) {
+      return { ok: false, error: 'Failed to list collections: HTTP ' + listResponse.status + '; log in to Instagram and retry.' };
+    }
+    const listData = await listResponse.json();
+    const collections = Array.isArray(listData?.items) ? listData.items : [];
+    const isNumericId = /^\\d{6,}$/.test(raw);
+    let id = '';
+    let resolvedName = '';
+    if (isNumericId) {
+      const hit = collections.find((collection) => String(collection?.collection_id) === raw);
+      if (!hit) return { ok: false, error: 'Collection id not found in your account: ' + raw };
+      id = String(hit.collection_id);
+      resolvedName = String(hit.collection_name || '');
+    } else {
+      const wanted = raw.toLowerCase();
+      const matches = collections.filter((collection) => String(collection?.collection_name || '').trim().toLowerCase() === wanted);
+      if (matches.length === 0) {
+        const names = collections.map((collection) => collection?.collection_name).filter(Boolean);
+        return { ok: false, error: 'Collection not found: ' + raw + '. Available: ' + (names.length ? names.join(', ') : '(none)') };
+      }
+      if (matches.length > 1) {
+        const ids = matches.map((collection) => collection.collection_id).join(', ');
+        return { ok: false, error: 'Multiple collections share the name "' + raw + '" (ids: ' + ids + '). Pass the numeric collection_id explicitly.' };
+      }
+      id = String(matches[0].collection_id);
+      resolvedName = String(matches[0].collection_name || raw);
+    }
+    const form = new FormData();
+    form.append('module_name', 'collection_settings');
+    const response = await fetch('https://www.instagram.com/api/v1/collections/' + encodeURIComponent(id) + '/delete/', {
+      method: 'POST',
+      credentials: 'include',
+      headers: { ...headers, 'X-CSRFToken': csrf },
+      body: form,
+    });
+    const text = await response.text();
+    let data = {};
+    try { data = text ? JSON.parse(text) : {}; } catch {}
+    if (!response.ok) {
+      return { ok: false, error: 'Failed to delete collection: HTTP ' + response.status + (text ? ' - ' + text.slice(0, 200) : '') };
+    }
+    if (data?.status && data.status !== 'ok') {
+      return { ok: false, error: 'Instagram returned non-ok status: ' + JSON.stringify(data).slice(0, 300) };
+    }
+    return {
+      ok: true,
+      row: {
+        status: 'Deleted',
+        collectionId: id,
+        collectionName: resolvedName,
+      },
+    };
+  })()`;
+}
+
+function mapCollectionRow(row: unknown): InstagramCollectionRow {
+  const value =
+    row && typeof row === "object" ? (row as InstagramCollectionRow) : {};
+  return {
+    status: String(value.status ?? ""),
+    collectionId: String(value.collectionId ?? ""),
+    collectionName: String(value.collectionName ?? ""),
+    mediaCount:
+      value.mediaCount === undefined
+        ? undefined
+        : Number(value.mediaCount) || 0,
+  };
+}
+
+cli({
+  site: "instagram",
+  name: "collection-create",
+  description: "Create a new Instagram saved-posts collection",
+  domain: "www.instagram.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "name", type: "str", required: true, positional: true }],
+  columns: ["status", "collectionId", "collectionName", "mediaCount"],
+  func: async (page, kwargs) => {
+    const name = requireInstagramCollectionInput(kwargs.name, "name");
+    const p = page as IPage;
+    await p.goto("https://www.instagram.com");
+    const result = (await p.evaluate(
+      buildCreateCollectionScript(name),
+    )) as InstagramCollectionResult;
+    if (!result?.ok) {
+      throw new Error(
+        String(result?.error || "Instagram collection create failed."),
+      );
+    }
+    return [mapCollectionRow(result.row)];
+  },
+});
+
+cli({
+  site: "instagram",
+  name: "collection-delete",
+  description: "Delete an Instagram saved-posts collection by name or id",
+  domain: "www.instagram.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "target", type: "str", required: true, positional: true }],
+  columns: ["status", "collectionId", "collectionName"],
+  func: async (page, kwargs) => {
+    const target = requireInstagramCollectionInput(kwargs.target, "target");
+    const p = page as IPage;
+    await p.goto("https://www.instagram.com");
+    const result = (await p.evaluate(
+      buildDeleteCollectionScript(target),
+    )) as InstagramCollectionResult;
+    if (!result?.ok) {
+      throw new Error(
+        String(result?.error || "Instagram collection delete failed."),
+      );
+    }
+    const row = mapCollectionRow(result.row);
+    return [
+      {
+        status: row.status,
+        collectionId: row.collectionId,
+        collectionName: row.collectionName,
+      },
+    ];
+  },
+});