@epsilon-asi/actors 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epsilon-asi/actors",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "A TypeScript Puppeteer actor framework using existing Chrome profiles and ghost-cursor.",
   "type": "module",
   "main": "dist/index.js",
@@ -24,13 +24,14 @@
     "clean": "rm -rf dist coverage"
   },
   "dependencies": {
+    "cheerio": "^1.2.0",
     "ghost-cursor": "^1.4.2",
     "puppeteer-core": "24.43.1"
   },
   "devDependencies": {
+    "@types/cheerio": "^0.22.35",
     "@types/node": "^24.10.1",
     "@vitest/coverage-v8": "^4.1.7",
-
     "vitest": "^4.1.7"
   },
   "engines": {

package/src/sites/upwork-com/upwork-com.actor.ts

@@ -1,97 +1,89 @@
 import {defineLoginFlow} from '../../auth/LoginFlow.types.js';
 import {defineActor} from '../../core/defineActor.js';
 import {upworkComSelectors} from './upwork-com.selectors.js';
-import type {
-  UpworkApplyToJobInput,
-  UpworkApplyToJobResult,
-  UpworkJobSearchFields,
-  UpworkJobSearchResult
-} from './upwork-com.types.js';
-import {buildSearchParams, parseRate} from "./upwork-com.util.js";
+import type {UpworkApplyToJobInput, UpworkApplyToJobResult, UpworkJobSearchFields} from './upwork-com.types.js';
+import {parseRate} from "./upwork-com.util.js";
+import {ScrapeDashboardInput} from "../example/index.js";
+import {parseUpworkSearchResults, UpworkJobListing} from "./util/scrapeJobListing.js";
+import {Page} from "puppeteer-core";
 
 export const upworkComActor = defineActor({
-  id: 'upwork-com',
-  baseUrl: 'https://upwork.com',
-  auth: defineLoginFlow({
-    loginUrl: 'https://www.upwork.com/ab/account-security/login',
-    selectors: {
-      loggedInSignal: upworkComSelectors.login.loggedInSignal,
-      errorMessage: upworkComSelectors.login.errorMessage
-    },
-    credentials: { id: 'upwork' },
-    behavior: {
-      authCheckUrl: '/',
-      loggedInTimeoutMs: 5_000,
-      errorTimeoutMs: 1_500,
-      typing: {
-        targetWordsPerMinute: 65,
-        intervalJitterMs: 18
-      }
-    },
-    steps: [
-      {
-        type: 'fill',
-        name: 'username',
-        selector: upworkComSelectors.login.username,
-        credential: 'username'
-      },
-      {
-        type: 'click',
-        name: 'continue to password',
-        selector: upworkComSelectors.login.continueToPassword,
-        waitForSelector: upworkComSelectors.login.password,
-        waitForSelectorTimeoutMs: 5_000
-      },
-      {
-        type: 'fill',
-        name: 'password',
-        selector: upworkComSelectors.login.password,
-        credential: 'password'
-      },
-      {
-        type: 'click',
-        name: 'submit password',
-        selector: upworkComSelectors.login.submit,
-        submit: true,
-        waitForNavigation: true,
-        checkForError: false
-      }
-    ]
-  }),
-  tasks: {
-    searchJobs: async (context, input: UpworkJobSearchFields = {}): Promise<any> => {
-      const path = '/nx/s/universal-search/jobs?client_hires=1-9,10-&payment_verified=1&q=%27rancher%27%20or%20%27terraform%27%20or%20%27gitops%27%20or%20%27azure%27%20or%20%27microsoft%20azure%27%20or%20%27cloud%20architect%27%20or%20%27ai%20architect%27%20or%20%27forward%20deployed%20engineer%27%20or%20%27aws%27%20or%20%27aks%27%20or%20%27eks%27%20or%20%27gke%27%20or%20%27cloud%20engineer%27%20or%20devops%20or%20kuberentes%20or%20%27platform%20engineer%27%20or%20%27infrastructure%20engineer%27%20or%20"google%20cloud%20platform"%20or%20"GCP"%20or%20"langsmith"%20or%20"langgraph"%20or%20"gemini%20enterprise"&sort=recency&user_location_match=1';
+    id: 'upwork-com',
+    baseUrl: 'https://upwork.com',
+    auth: defineLoginFlow({
+        loginUrl: 'https://www.upwork.com/ab/account-security/login',
+        selectors: {
+            loggedInSignal: upworkComSelectors.login.loggedInSignal,
+            errorMessage: upworkComSelectors.login.errorMessage
+        },
+        credentials: {id: 'upwork'},
+        behavior: {
+            authCheckUrl: '/',
+            loggedInTimeoutMs: 5_000,
+            errorTimeoutMs: 1_500,
+            typing: {
+                targetWordsPerMinute: 65,
+                intervalJitterMs: 18
+            }
+        },
+        steps: [
+            {
+                type: 'fill',
+                name: 'username',
+                selector: upworkComSelectors.login.username,
+                credential: 'username'
+            },
+            {
+                type: 'click',
+                name: 'continue to password',
+                selector: upworkComSelectors.login.continueToPassword,
+                waitForSelector: upworkComSelectors.login.password,
+                waitForSelectorTimeoutMs: 5_000
+            },
+            {
+                type: 'fill',
+                name: 'password',
+                selector: upworkComSelectors.login.password,
+                credential: 'password'
+            },
+            {
+                type: 'click',
+                name: 'submit password',
+                selector: upworkComSelectors.login.submit,
+                submit: true,
+                waitForNavigation: true,
+                checkForError: false
+            }
+        ]
+    }),
+    tasks: {
+        searchJobs: async (context, input: UpworkJobSearchFields = {}): Promise<UpworkJobListing[]> => {
+            const path = '/nx/s/universal-search/jobs?category2_uid=531770282580668420,531770282580668419,531770282580668418&client_hires=1-9,10-&payment_verified=1&q=%27rancher%27%20or%20%27terraform%27%20or%20%27gitops%27%20or%20%27azure%27%20or%20%27microsoft%20azure%27%20or%20%27cloud%20architect%27%20or%20%27ai%20architect%27%20or%20%27forward%20deployed%20engineer%27%20or%20%27aws%27%20or%20%27aks%27%20or%20%27eks%27%20or%20%27gke%27%20or%20%27cloud%20engineer%27%20or%20devops%20or%20kuberentes%20or%20%27platform%20engineer%27%20or%20%27infrastructure%20engineer%27%20or%20"google%20cloud%20platform"%20or%20"GCP"%20or%20"langsmith"%20or%20"langgraph"%20or%20"gemini%20enterprise"&sort=recency&user_location_match=1';
 
-      await context.nav.goto(path, {});
+            await context.nav.goto(path, {
 
-      console.log(context.page.raw());
+            });
 
-      // Get by classname class="jobs-main-panel - get all children of article type
-      // loop through each. Check
-        //
-      //
-    },
-    applyToJob: async (_context, input: UpworkApplyToJobInput): Promise<UpworkApplyToJobResult> => {
-      const coverLetter = input.coverLetter.trim();
-      if (coverLetter.length === 0) {
-        throw new Error('coverLetter must be a non-empty string.');
-      }
+            return await parseUpworkSearchResults(context.session.page as Page);
+        },
+        scrapeJobs: async (context, input: ScrapeDashboardInput = {}): Promise<any> => {
+            await parseUpworkSearchResults(context.session.page as Page)
+        },
+        applyToJob: async (_context, input: UpworkApplyToJobInput): Promise<UpworkApplyToJobResult> => {
+            const coverLetter = input.coverLetter.trim();
+            if (coverLetter.length === 0) {
+                throw new Error('coverLetter must be a non-empty string.');
+            }
 
-      const rate = parseRate(input.rate);
-      if (!Number.isFinite(rate) || rate <= 0) {
-        throw new Error('rate must be a positive number.');
-      }
+            const rate = parseRate(input.rate);
+            if (!Number.isFinite(rate) || rate <= 0) {
+                throw new Error('rate must be a positive number.');
+            }
 
-      return {
-        coverLetter,
-        rate
-      };
+            return {
+                coverLetter,
+                rate
+            };
+        }
     }
-  }
 });
-
-
-const likeScript = `reactions.action_reactions(this, 1632181); `
-const commentScript = `activity.comment_save(1630927, this);`
-
-

package/src/sites/upwork-com/util/parseJobDetails.ts

@@ -0,0 +1,573 @@
+import * as cheerio from "cheerio";
+import {z} from "zod/v4";
+
+/**
+ * ============================================================================
+ * Upwork Job Details Page Parser
+ * ============================================================================
+ *
+ * Parses the FULL Upwork job details page HTML into a strongly typed object.
+ *
+ * Designed for:
+ * - Saved HTML snapshots
+ * - Browser automation scraping
+ * - Puppeteer / Playwright extraction
+ * - LangGraph / AI ingestion pipelines
+ *
+ * This parser intentionally avoids brittle class names wherever possible and
+ * instead relies on semantic structure and textual anchors.
+ */
+
+/* =============================================================================
+ * Zod Schemas
+ * ========================================================================== */
+
+export const UpworkClientReviewSchema = z.object({
+    jobTitle: z.string().nullable(),
+    feedback: z.string().nullable(),
+    freelancerName: z.string().nullable(),
+    rating: z.number().nullable(),
+    engagementType: z.string().nullable(),
+    amount: z.string().nullable(),
+    dateRange: z.string().nullable(),
+});
+
+export type UpworkClientReview = z.infer<
+    typeof UpworkClientReviewSchema
+>;
+
+export const UpworkClientSchema = z.object({
+    paymentVerified: z.boolean(),
+
+    phoneVerified: z.boolean(),
+
+    rating: z.number().nullable(),
+
+    reviewCount: z.number().nullable(),
+
+    country: z.string().nullable(),
+
+    city: z.string().nullable(),
+
+    localTime: z.string().nullable(),
+
+    jobsPosted: z.number().nullable(),
+
+    hireRate: z.number().nullable(),
+
+    openJobs: z.number().nullable(),
+
+    totalSpent: z.string().nullable(),
+
+    hires: z.number().nullable(),
+
+    activeHires: z.number().nullable(),
+
+    avgHourlyRatePaid: z.string().nullable(),
+
+    totalHours: z.number().nullable(),
+
+    memberSince: z.string().nullable(),
+
+    recentHistory: z.array(UpworkClientReviewSchema),
+});
+
+export type UpworkClient = z.infer<typeof UpworkClientSchema>;
+
+export const UpworkJobDetailsSchema = z.object({
+    jobUrl: z.string().nullable(),
+
+    projectType: z.string().nullable(),
+
+    mandatorySkills: z.array(z.string()),
+
+    preferredQualifications: z.object({
+        location: z.string().nullable(),
+    }),
+
+    activity: z.object({
+        proposals: z.string().nullable(),
+        interviewing: z.number().nullable(),
+        invitesSent: z.number().nullable(),
+        unansweredInvites: z.number().nullable(),
+    }),
+
+    connectsRequired: z.number().nullable(),
+
+    availableConnects: z.number().nullable(),
+
+    client: UpworkClientSchema,
+
+    otherOpenJobs: z.array(
+        z.object({
+            title: z.string(),
+            type: z.string().nullable(),
+        }),
+    ),
+});
+
+export type UpworkJobDetails = z.infer<
+    typeof UpworkJobDetailsSchema
+>;
+
+/* =============================================================================
+ * Utility Helpers
+ * ========================================================================== */
+
+function cleanText(input?: string | null): string {
+    return (input ?? "")
+        .replace(/\s+/g, " ")
+        .replace(/\u00a0/g, " ")
+        .trim();
+}
+
+function extractNumber(input?: string | null): number | null {
+    if (!input) return null;
+
+    const match = input.match(/-?\d+(\.\d+)?/);
+
+    if (!match) return null;
+
+    return Number(match[0]);
+}
+
+function extractStrongLabelValue(
+    $root: cheerio.Cheerio<any>,
+    label: string,
+): string | null {
+    const strong = $root
+        .find("strong")
+        .filter((_, el) =>
+            cleanText($root.eq(0).find(el).text())
+                .toLowerCase()
+                .startsWith(label.toLowerCase()),
+        )
+        .first();
+
+    if (!strong.length) return null;
+
+    const parentText = cleanText(strong.parent().text());
+
+    return cleanText(
+        parentText.replace(strong.text(), ""),
+    );
+}
+
+/* =============================================================================
+ * Main Parser
+ * ========================================================================== */
+
+export function parseUpworkJobDetailsPage(
+    html: string,
+): UpworkJobDetails {
+    const $ = cheerio.load(html);
+
+    /* ===========================================================================
+     * Project Type
+     * ========================================================================= */
+
+    const projectType = cleanText(
+        $("li")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .toLowerCase()
+                    .includes("project type:"),
+            )
+            .first()
+            .text()
+            .replace(/project type:/i, ""),
+    ) || null;
+
+    /* ===========================================================================
+     * Skills
+     * ========================================================================= */
+
+    const mandatorySkills: string[] = [];
+
+    $("h5")
+        .filter((_, el) =>
+            cleanText($(el).text())
+                .toLowerCase()
+                .includes("skills and expertise"),
+        )
+        .closest("section")
+        .find(".skills-list a")
+        .each((_, el) => {
+            const skill = cleanText($(el).text());
+
+            if (skill) {
+                mandatorySkills.push(skill);
+            }
+        });
+
+    /* ===========================================================================
+     * Preferred Qualifications
+     * ========================================================================= */
+
+    const qualificationSection = $("h5")
+        .filter((_, el) =>
+            cleanText($(el).text())
+                .toLowerCase()
+                .includes("preferred qualifications"),
+        )
+        .closest("section");
+
+    const preferredLocation =
+        extractStrongLabelValue(
+            qualificationSection,
+            "Location:",
+        );
+
+    /* ===========================================================================
+     * Activity
+     * ========================================================================= */
+
+    const activitySection = $("h5")
+        .filter((_, el) =>
+            cleanText($(el).text())
+                .toLowerCase()
+                .includes("activity on this job"),
+        )
+        .closest("section");
+
+    const proposals = cleanText(
+        activitySection
+            .find(".ca-item")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .toLowerCase()
+                    .includes("proposals:"),
+            )
+            .find(".value")
+            .text(),
+    ) || null;
+
+    const interviewing = extractNumber(
+        activitySection
+            .find(".ca-item")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .toLowerCase()
+                    .includes("interviewing:"),
+            )
+            .find(".value")
+            .text(),
+    );
+
+    const invitesSent = extractNumber(
+        activitySection
+            .find(".ca-item")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .toLowerCase()
+                    .includes("invites sent:"),
+            )
+            .find(".value")
+            .text(),
+    );
+
+    const unansweredInvites = extractNumber(
+        activitySection
+            .find(".ca-item")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .toLowerCase()
+                    .includes("unanswered invites:"),
+            )
+            .find(".value")
+            .text(),
+    );
+
+    /* ===========================================================================
+     * Connects
+     * ========================================================================= */
+
+    const connectsRequired = extractNumber(
+        $("div")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .includes("Send a proposal for:"),
+            )
+            .text(),
+    );
+
+    const availableConnects = extractNumber(
+        $("div")
+            .filter((_, el) =>
+                cleanText($(el).text())
+                    .includes("Available Connects:"),
+            )
+            .text(),
+    );
+
+    /* ===========================================================================
+     * Job URL
+     * ========================================================================= */
+
+    const jobUrl =
+        $("input[aria-label='Job link']").attr("value") ??
+        null;
+
+    /* ===========================================================================
+     * Client Section
+     * ========================================================================= */
+
+    const clientSection = $(
+        "[data-test='about-client-container']",
+    );
+
+    const paymentVerified =
+        cleanText(clientSection.text())
+            .toLowerCase()
+            .includes("payment method verified");
+
+    const phoneVerified =
+        cleanText(clientSection.text())
+            .toLowerCase()
+            .includes("phone number verified");
+
+    const rating = extractNumber(
+        clientSection
+            .find("[data-testid='buyer-rating']")
+            .text(),
+    );
+
+    const reviewCount = extractNumber(
+        clientSection
+            .find("[data-testid='buyer-rating']")
+            .text()
+            .match(/of\s+(\d+)\s+reviews/i)?.[1],
+    );
+
+    const country = cleanText(
+        clientSection
+            .find("[data-qa='client-location'] strong")
+            .first()
+            .text(),
+    ) || null;
+
+    const locationText = cleanText(
+        clientSection
+            .find("[data-qa='client-location'] div")
+            .text(),
+    );
+
+    const city =
+        locationText.split(/\d/)[0]?.trim() || null;
+
+    const localTimeMatch =
+        locationText.match(/\d{1,2}:\d{2}\s?[AP]M/i);
+
+    const localTime = localTimeMatch?.[0] ?? null;
+
+    const jobsPosted = extractNumber(
+        clientSection
+            .find("[data-qa='client-job-posting-stats']")
+            .text(),
+    );
+
+    const hireRate = extractNumber(
+        clientSection
+            .find("[data-qa='client-job-posting-stats']")
+            .text()
+            .match(/(\d+)% hire rate/i)?.[1],
+    );
+
+    const openJobs = extractNumber(
+        clientSection
+            .find("[data-qa='client-job-posting-stats']")
+            .text()
+            .match(/(\d+) open jobs/i)?.[1],
+    );
+
+    const totalSpent = cleanText(
+        clientSection
+            .find("[data-qa='client-spend']")
+            .text(),
+    ) || null;
+
+    const hires = extractNumber(
+        clientSection
+            .find("[data-qa='client-hires']")
+            .text()
+            .match(/(\d+) hires/i)?.[1],
+    );
+
+    const activeHires = extractNumber(
+        clientSection
+            .find("[data-qa='client-hires']")
+            .text()
+            .match(/(\d+) active/i)?.[1],
+    );
+
+    const avgHourlyRatePaid = cleanText(
+        clientSection
+            .find("[data-qa='client-hourly-rate']")
+            .text(),
+    ) || null;
+
+    const totalHours = extractNumber(
+        clientSection
+            .find("[data-qa='client-hours']")
+            .text(),
+    );
+
+    const memberSince = cleanText(
+        clientSection
+            .find("[data-qa='client-contract-date']")
+            .text(),
+    ) || null;
+
+    /* ===========================================================================
+     * Recent History
+     * ========================================================================= */
+
+    const recentHistory: UpworkClientReview[] = [];
+
+    $("[data-cy='job']").each((_, el) => {
+        const $job = $(el);
+
+        const jobTitle = cleanText(
+            $job.find("[data-cy='job-title']").text(),
+        );
+
+        const feedback = cleanText(
+            $job
+                .find(".air3-truncation")
+                .first()
+                .text(),
+        );
+
+        const freelancerName = cleanText(
+            $job
+                .find("a[href*='/freelancers/']")
+                .first()
+                .text(),
+        );
+
+        const rating = extractNumber(
+            $job.find(".air3-rating-value-text").first().text(),
+        );
+
+        const stats = cleanText(
+            $job.find("[data-cy='stats']").text(),
+        );
+
+        const engagementType =
+            stats.split("$")[0]?.trim() || null;
+
+        const amountMatch = stats.match(
+            /\$\d+(?:,\d+)?(?:\.\d+)?/,
+        );
+
+        const amount = amountMatch?.[0] ?? null;
+
+        const dateRange = cleanText(
+            $job.find("[data-cy='date']").text(),
+        );
+
+        recentHistory.push(
+            UpworkClientReviewSchema.parse({
+                jobTitle: jobTitle || null,
+                feedback: feedback || null,
+                freelancerName: freelancerName || null,
+                rating,
+                engagementType,
+                amount,
+                dateRange: dateRange || null,
+            }),
+        );
+    });
+
+    /* ===========================================================================
+     * Other Open Jobs
+     * ========================================================================= */
+
+    const otherOpenJobs: Array<{
+        title: string;
+        type: string | null;
+    }> = [];
+
+    $("#otherOpenJobs li").each((_, el) => {
+        const title = cleanText(
+            $(el).find("a").text(),
+        );
+
+        const type = cleanText(
+            $(el).find(".type").text(),
+        );
+
+        if (title) {
+            otherOpenJobs.push({
+                title,
+                type: type || null,
+            });
+        }
+    });
+
+    /* ===========================================================================
+     * Final Object
+     * ========================================================================= */
+
+    return UpworkJobDetailsSchema.parse({
+        jobUrl,
+
+        projectType,
+
+        mandatorySkills,
+
+        preferredQualifications: {
+            location: preferredLocation,
+        },
+
+        activity: {
+            proposals,
+            interviewing,
+            invitesSent,
+            unansweredInvites,
+        },
+
+        connectsRequired,
+
+        availableConnects,
+
+        client: {
+            paymentVerified,
+
+            phoneVerified,
+
+            rating,
+
+            reviewCount,
+
+            country,
+
+            city,
+
+            localTime,
+
+            jobsPosted,
+
+            hireRate,
+
+            openJobs,
+
+            totalSpent,
+
+            hires,
+
+            activeHires,
+
+            avgHourlyRatePaid,
+
+            totalHours,
+
+            memberSince,
+
+            recentHistory,
+        },
+
+        otherOpenJobs,
+    });
+}
+

package/src/sites/upwork-com/util/scrapeJobListing.ts

@@ -0,0 +1,300 @@
+import type {ElementHandle, Page} from "puppeteer-core";
+import {z} from "zod/v4";
+
+/* -------------------------------------------------------------------------------------------------
+ * Zod Schemas
+ * ------------------------------------------------------------------------------------------------- */
+export enum JobCategoryType {
+    "hourly" = "hourly",
+    "fixed" = "fixed",
+}
+
+export const UpworkJobListingSchema = z.object({
+    id: z.string(),
+
+    title: z.string(),
+    url: z.string(),
+
+    postedAtText: z.string().nullable(),
+    proposalsText: z.string().nullable(),
+
+    description: z.string(),
+
+    skills: z.array(z.string()),
+
+    category: z.object({
+        type: z.enum(JobCategoryType, {}).nullable(),
+        raw: z.string().nullable(),
+    }),
+
+    hourlyRate: z
+        .object({
+            min: z.number().nullable(),
+            max: z.number().nullable(),
+            raw: z.string().nullable(),
+        })
+        .nullable(),
+
+    fixedBudget: z
+        .object({
+            amount: z.number().nullable(),
+            raw: z.string().nullable(),
+        })
+        .nullable(),
+
+    experienceLevel: z.string().nullable(),
+
+    estimatedTime: z.string().nullable(),
+
+    client: z.object({
+        paymentVerified: z.boolean(),
+
+        rating: z.number().nullable(),
+
+        totalSpent: z.string().nullable(),
+
+        location: z.string().nullable(),
+    }),
+
+    rawText: z.string(),
+});
+
+export type UpworkJobListing = z.infer<typeof UpworkJobListingSchema>;
+
+/* -------------------------------------------------------------------------------------------------
+ * Helpers
+ * ------------------------------------------------------------------------------------------------- */
+
+function cleanText(input?: string | null): string {
+    return (input ?? "")
+        .replace(/\s+/g, " ")
+        .replace(/\u00a0/g, " ")
+        .trim();
+}
+
+function parseMoney(value?: string): number | null {
+    if (!value) return null;
+    const normalized = value.replace(/[^0-9.]/g, "");
+
+    if (!normalized) {
+        return null;
+    }
+
+    const parsed = Number(normalized);
+
+    return Number.isNaN(parsed) ? null : parsed;
+}
+
+function parseHourlyRate(
+    raw: string | null,
+): UpworkJobListing["hourlyRate"] {
+    if (!raw) {
+        return null;
+    }
+
+    const matches = raw.match(/\$([\d,.]+)\s*-\s*\$([\d,.]+)/);
+
+    if (!matches || matches.length < 3) {
+        return {
+            min: null,
+            max: null,
+            raw,
+        };
+    }
+    return {
+        min: parseMoney(matches[1]),
+        max: parseMoney(matches[2]),
+        raw,
+    };
+}
+
+function parseFixedBudget(
+    raw: string | null,
+): UpworkJobListing["fixedBudget"] {
+    if (!raw) {
+        return null;
+    }
+
+    const match = raw.match(/\$([\d,.]+)/);
+
+    return {
+        amount: match ? parseMoney(match[1]) : null,
+        raw,
+    };
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Core Parser
+ * ------------------------------------------------------------------------------------------------- */
+
+export async function parseUpworkJobListing(
+    article: ElementHandle<Element>,
+): Promise<UpworkJobListing> {
+    const extracted = await article.evaluate((node) => {
+        const getText = (selector: string): string | null => {
+            const element = node.querySelector(selector);
+
+            return element?.textContent?.trim() ?? null;
+        };
+
+        const getTexts = (selector: string): string[] => {
+            return Array.from(node.querySelectorAll(selector))
+                .map((el) => el.textContent?.trim() ?? "")
+                .filter(Boolean);
+        };
+
+        const titleAnchor = node.querySelector(
+            '[data-test="job-tile-title-link UpLink"]',
+        ) as HTMLAnchorElement | null;
+
+        const jobInfoItems = Array.from(
+            node.querySelectorAll('[data-test="JobInfo"] li'),
+        ).map((li) => li.textContent?.trim() ?? "");
+
+        const clientInfoItems = Array.from(
+            node.querySelectorAll('[data-test="JobInfoClient"] li'),
+        ).map((li) => li.textContent?.trim() ?? "");
+
+        const hourlyItem =
+            jobInfoItems.find((x) => x.toLowerCase().includes("hourly")) ?? null;
+
+        const fixedItem =
+            jobInfoItems.find((x) => x.toLowerCase().includes("fixed")) ?? null;
+
+        const experienceLevel =
+            node
+                .querySelector('[data-test="experience-level"]')
+                ?.textContent?.trim() ?? null;
+
+        const estimatedTime =
+            node
+                .querySelector('[data-test="duration-label"]')
+                ?.textContent?.trim() ?? null;
+
+        const ratingText =
+            node
+                .querySelector('[data-test="feedback-rating UpCRating"]')
+                ?.textContent?.trim() ?? null;
+
+        const spentText =
+            node
+                .querySelector('[data-test="total-spent"]')
+                ?.textContent?.trim() ?? null;
+
+        const locationText =
+            node
+                .querySelector('[data-test="location"]')
+                ?.textContent?.trim() ?? null;
+
+        return {
+            id:
+                node.getAttribute("data-ev-job-uid") ??
+                node.getAttribute("data-test-key") ??
+                "",
+
+            title: titleAnchor?.textContent?.trim() ?? "",
+
+            url: titleAnchor?.href ?? "",
+
+            postedAtText:
+                getText('[data-test="job-pubilshed-date"] span:first-child') ?? null,
+
+            proposalsText:
+                getText('[data-test="proposals-tier"]') ?? null,
+
+            description:
+                getText('[data-test="UpCLineClamp JobDescription"] p') ?? "",
+
+            skills: getTexts('[data-test="token"] span'),
+
+            hourlyRaw: hourlyItem,
+            fixedRaw: fixedItem,
+
+            experienceLevel,
+            estimatedTime,
+
+            paymentVerified:
+                node.querySelector('[data-test="payment-verified"]') !== null,
+
+            ratingText,
+            spentText,
+            locationText,
+
+            rawText: node.textContent ?? "",
+
+            categoryType: hourlyItem
+                ? "hourly"
+                : fixedItem
+                    ? "fixed"
+                    : null,
+        };
+    });
+
+    const hourlyRate = parseHourlyRate(extracted.hourlyRaw);
+    const fixedBudget = parseFixedBudget(extracted.fixedRaw);
+
+    const ratingMatch = extracted.ratingText?.match(/(\d+(\.\d+)?)/);
+
+    const parsed: UpworkJobListing = {
+        id: cleanText(extracted.id),
+
+        title: cleanText(extracted.title),
+
+        url: cleanText(extracted.url),
+
+        postedAtText: cleanText(extracted.postedAtText),
+
+        proposalsText: cleanText(extracted.proposalsText),
+
+        description: cleanText(extracted.description),
+
+        skills: extracted.skills.map(cleanText),
+
+        category: {
+            type: extracted.categoryType as (JobCategoryType | null),
+            raw: cleanText(extracted.hourlyRaw ?? extracted.fixedRaw),
+        },
+
+        hourlyRate,
+
+        fixedBudget,
+
+        experienceLevel: cleanText(extracted.experienceLevel),
+
+        estimatedTime: cleanText(extracted.estimatedTime),
+
+        client: {
+            paymentVerified: extracted.paymentVerified,
+
+            rating: ratingMatch ? Number(ratingMatch[1]) : null,
+
+            totalSpent: cleanText(extracted.spentText),
+
+            location: cleanText(extracted.locationText),
+        },
+
+        rawText: cleanText(extracted.rawText),
+    };
+
+    return UpworkJobListingSchema.parse(parsed);
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Multi-Listing Parser
+ * ------------------------------------------------------------------------------------------------- */
+
+export async function parseUpworkSearchResults(
+    page: Page,
+): Promise<UpworkJobListing[]> {
+    await page.waitForSelector('#main > section > article[data-ev-sublocation="search_results"]');
+
+    const articles = await page.$$(
+        '#main > section > article[data-ev-sublocation="search_results"]',
+    );
+
+    const results = await Promise.all(
+        articles.map((article) => parseUpworkJobListing(article)),
+    );
+
+    return results;
+}