@jackwener/opencli 1.8.0 → 1.8.1

package/clis/upwork/utils.js

@@ -0,0 +1,323 @@
+/**
+ * Upwork adapter utilities.
+ *
+ * Upwork is a Nuxt (Vue) SSR app behind Cloudflare. Every adapter runs
+ * through the user's logged-in browser session (Strategy.COOKIE,
+ * browser: true) because bare fetches hit a `__cf_bm` challenge and
+ * because most surfaces only render data for an authenticated user.
+ *
+ * The list pages (search, best-matches feed) ship their full result
+ * payload inside `window.__NUXT__.state` — we read straight from that
+ * global instead of DOM-scraping rendered cards. Job detail uses the
+ * Vuex store (`window.$nuxt.$store.state.jobDetails.*`). All helpers
+ * below are pure (arg validation, decoders, URL builders, row mappers)
+ * so they stay unit-testable without a browser.
+ */
+
+import {
+    ArgumentError,
+    CommandExecutionError,
+} from '@jackwener/opencli/errors';
+
+export const UPWORK_ORIGIN = 'https://www.upwork.com';
+
+const CIPHERTEXT_PATTERN = /^~0[12]\d{15,21}$/;
+
+const FEED_TABS = {
+    'best-matches': { path: '/nx/find-work/best-matches', state: 'feedBestMatch' },
+    'most-recent': { path: '/nx/find-work/most-recent', state: 'feedMostRecent' },
+};
+
+const SORT_VALUES = new Set(['recency', 'relevance', 'client_total_charge', 'client_total_reviews']);
+
+export function unwrapBrowserResult(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && 'session' in value && 'data' in value) {
+        return value.data;
+    }
+    return value;
+}
+
+export function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function coerceInt(value) {
+    if (value === undefined || value === null || value === '') return NaN;
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) && Number.isInteger(n) ? n : NaN;
+}
+
+export function requireQuery(value, label = 'query') {
+    const q = String(value ?? '').trim();
+    if (!q) throw new ArgumentError(`upwork ${label} cannot be empty`);
+    return q;
+}
+
+export function requirePositiveInt(value, defaultValue, label) {
+    const raw = value ?? defaultValue;
+    const n = coerceInt(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`upwork ${label} must be a positive integer`);
+    }
+    return n;
+}
+
+export function requireBoundedInt(value, defaultValue, min, max, label) {
+    const n = requirePositiveInt(value, defaultValue, label);
+    if (n < min) throw new ArgumentError(`upwork ${label} must be >= ${min}`);
+    if (n > max) throw new ArgumentError(`upwork ${label} must be <= ${max}`);
+    return n;
+}
+
+/**
+ * Upwork job ids are the ciphertext form starting with `~01` or `~02`
+ * (the encoded uid surfaced everywhere in URLs and search results).
+ * Accepts a bare ciphertext or a full `/jobs/~02…` URL.
+ */
+export function requireCiphertext(value) {
+    let id = String(value ?? '').trim();
+    if (!id) throw new ArgumentError('upwork job id is required');
+    const urlMatch = id.match(/~0[12]\d+/);
+    if (urlMatch) id = urlMatch[0];
+    if (!CIPHERTEXT_PATTERN.test(id)) {
+        throw new ArgumentError(`upwork job id "${value}" is not a valid ciphertext (expected ~01… or ~02… followed by digits)`);
+    }
+    return id;
+}
+
+export function requireFeedTab(value, defaultValue = 'best-matches') {
+    const v = String(value ?? defaultValue).trim().toLowerCase();
+    if (!FEED_TABS[v]) {
+        throw new ArgumentError(`upwork tab must be one of ${Object.keys(FEED_TABS).join(' / ')}, got "${value}"`);
+    }
+    return v;
+}
+
+export function requireSort(value, defaultValue = 'recency') {
+    const v = String(value ?? defaultValue).trim().toLowerCase();
+    if (!SORT_VALUES.has(v)) {
+        throw new ArgumentError(`upwork sort must be one of ${Array.from(SORT_VALUES).join(' / ')}, got "${value}"`);
+    }
+    return v;
+}
+
+/**
+ * Build the Upwork search URL. Only forwards filters the user actually
+ * supplied so the URL stays canonical and round-trippable.
+ */
+export function buildSearchUrl({ query, location, category, sort, page, perPage }) {
+    const params = new URLSearchParams();
+    params.set('q', query);
+    if (location) params.set('location', location);
+    if (category) params.set('category2_uid', category);
+    if (sort && sort !== 'recency') params.set('sort', sort);
+    if (perPage && perPage !== 10) params.set('per_page', String(perPage));
+    if (page && page > 1) params.set('page', String(page));
+    return `${UPWORK_ORIGIN}/nx/search/jobs/?${params.toString()}`;
+}
+
+export function buildFeedUrl(tab) {
+    const t = FEED_TABS[tab];
+    if (!t) throw new ArgumentError(`unknown feed tab "${tab}"`);
+    return `${UPWORK_ORIGIN}${t.path}`;
+}
+
+export function feedStateKey(tab) {
+    const t = FEED_TABS[tab];
+    if (!t) throw new ArgumentError(`unknown feed tab "${tab}"`);
+    return t.state;
+}
+
+export function buildJobUrl(ciphertext) {
+    return `${UPWORK_ORIGIN}/jobs/${ciphertext}`;
+}
+
+export function isValidCiphertext(value) {
+    return CIPHERTEXT_PATTERN.test(String(value ?? '').trim());
+}
+
+/**
+ * Strip Upwork's `<span class="highlight">…</span>` markup that wraps
+ * matched query terms in search results, then collapse whitespace.
+ * Empty / null returns ''.
+ */
+export function stripHighlight(text) {
+    if (text == null) return '';
+    return String(text)
+        .replace(/<span class="highlight">/g, '')
+        .replace(/<\/span>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/**
+ * Decode `tierText` codes into stable lowercase labels.
+ *   - search rows use the i18n-keyed form: `jsn_Entry_205` / `_Intermediate_206` / `_Expert_207`
+ *   - feed rows already pass through the rendered label: `Entry level` / `Intermediate` / `Expert`
+ *   - detail uses a numeric `contractorTier`: 1 / 2 / 3
+ * Returns 'entry' | 'intermediate' | 'expert' | '' (unknown).
+ */
+export function decodeExperienceLevel(value) {
+    if (value == null || value === '') return '';
+    if (typeof value === 'number') {
+        if (value === 1) return 'entry';
+        if (value === 2) return 'intermediate';
+        if (value === 3) return 'expert';
+        return '';
+    }
+    const v = String(value).toLowerCase();
+    if (v.includes('entry')) return 'entry';
+    if (v.includes('intermediate')) return 'intermediate';
+    if (v.includes('expert')) return 'expert';
+    return '';
+}
+
+/**
+ * Decode the `engagement` workload code. Search rows ship it as
+ * `usnuxt_Engagement_421.fullTime` / `.partTime`; detail surfaces it
+ * pre-rendered as `More than 30 hrs/week`. Returns 'full-time' /
+ * 'part-time' / '' or passes the rendered string through.
+ */
+export function decodeWorkload(value) {
+    if (value == null || value === '') return '';
+    const v = String(value);
+    const suffix = v.includes('.') ? v.split('.').pop() : v;
+    const lower = suffix.toLowerCase();
+    if (lower === 'fulltime' || lower.includes('full')) return 'full-time';
+    if (lower === 'parttime' || lower.includes('part')) return 'part-time';
+    if (lower.includes('hrs/week') || lower.includes('hours')) return suffix.trim();
+    return '';
+}
+
+/**
+ * Decode `proposalsTier` to a compact bucket label. Search ships it as
+ * `usnuxt_JobProposalTier_418.lessThan5` etc; feed ships it pre-rendered
+ * as `15 to 20` / `5 to 10`. Returns the bucket like '<5' / '5-10' /
+ * '20-50' / '50+', or '' if unrecognized.
+ */
+export function decodeProposalsTier(value) {
+    if (value == null || value === '') return '';
+    const v = String(value);
+    const suffix = v.includes('.') ? v.split('.').pop() : v;
+    const s = suffix.trim();
+    if (/^lessThan(\d+)$/i.test(s)) return `<${s.match(/\d+/)[0]}`;
+    if (/^(\d+)plus$/i.test(s)) return `${s.match(/\d+/)[0]}+`;
+    const range = s.match(/^(\d+)\s*(?:to|-|–)\s*(\d+)$/i);
+    if (range) return `${range[1]}-${range[2]}`;
+    return s;
+}
+
+/**
+ * Format the budget into a single human-readable column.
+ *   - hourly (type 2):  "$40-$70/hr"  or "$30/hr"  or "" (no budget set)
+ *   - fixed  (type 1):  "$200"  or "" (no amount)
+ * Used by search/feed; detail uses formatBudgetFromDetail (different shape).
+ */
+export function formatBudget(job) {
+    const type = job?.type;
+    const min = Number(job?.hourlyBudget?.min) || 0;
+    const max = Number(job?.hourlyBudget?.max) || 0;
+    const amount = Number(job?.amount?.amount) || 0;
+    if (type === 2) {
+        if (min > 0 && max > 0 && max !== min) return `$${min}-$${max}/hr`;
+        if (max > 0) return `$${max}/hr`;
+        if (min > 0) return `$${min}/hr`;
+        return '';
+    }
+    if (type === 1) return amount > 0 ? `$${amount}` : '';
+    return '';
+}
+
+/** Detail page uses `extendedBudgetInfo.{hourlyBudgetMin,Max}` + `budget.amount`. */
+export function formatBudgetFromDetail(job) {
+    const type = job?.type;
+    const min = Number(job?.extendedBudgetInfo?.hourlyBudgetMin) || 0;
+    const max = Number(job?.extendedBudgetInfo?.hourlyBudgetMax) || 0;
+    const amount = Number(job?.budget?.amount) || 0;
+    if (type === 2) {
+        if (min > 0 && max > 0 && max !== min) return `$${min}-$${max}/hr`;
+        if (max > 0) return `$${max}/hr`;
+        if (min > 0) return `$${min}/hr`;
+        return '';
+    }
+    if (type === 1) return amount > 0 ? `$${amount}` : '';
+    return '';
+}
+
+export function jobType(type) {
+    if (type === 1) return 'fixed';
+    if (type === 2) return 'hourly';
+    return '';
+}
+
+/**
+ * Join skills/attrs into a comma-separated string. Search rows have
+ * `attrs[].prettyName`; feed rows additionally have `skills[].prefLabel`;
+ * detail has neither (skills live elsewhere). The function picks
+ * whichever array is populated and dedupes.
+ */
+export function formatSkills(job) {
+    const candidates = [];
+    const arrs = [job?.attrs, job?.skills, job?.ontologySkills];
+    for (const arr of arrs) {
+        if (!Array.isArray(arr)) continue;
+        for (const s of arr) {
+            const name = (s?.prettyName ?? s?.prefLabel ?? s?.name ?? '').trim();
+            if (name && !candidates.includes(name)) candidates.push(name);
+        }
+    }
+    return candidates.join(', ');
+}
+
+/**
+ * Normalize a search/feed job entry into the shared LIST_COLUMNS row shape.
+ * Returns null when the row lacks a round-trippable ciphertext identity.
+ */
+export function jobToListRow(job, rank) {
+    const id = String(job?.ciphertext ?? '').trim();
+    if (!isValidCiphertext(id)) return null;
+    const client = job?.client || {};
+    const country = client?.location?.country || '';
+    const rating = Number(client?.totalFeedback);
+    return {
+        rank,
+        id,
+        title: stripHighlight(job?.title),
+        type: jobType(job?.type),
+        budget: formatBudget(job),
+        experienceLevel: decodeExperienceLevel(job?.tierText ?? job?.tier),
+        proposalsTier: decodeProposalsTier(job?.proposalsTier),
+        skills: formatSkills(job),
+        clientCountry: country,
+        clientRating: Number.isFinite(rating) && rating > 0 ? rating : null,
+        publishedOn: job?.publishedOn || job?.createdOn || '',
+        url: buildJobUrl(id),
+    };
+}
+
+export function jobsToListRows(jobs, { offset = 0, limit } = {}) {
+    const rows = [];
+    const source = limit ? jobs.slice(0, limit) : jobs;
+    for (const [index, job] of source.entries()) {
+        const rank = offset + index + 1;
+        const row = jobToListRow(job, rank);
+        if (!row) {
+            throw new CommandExecutionError(`Upwork result at rank ${rank} did not include a valid ciphertext id; cannot produce round-trippable detail rows.`);
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+
+export const LIST_COLUMNS = [
+    'rank', 'id', 'title', 'type', 'budget',
+    'experienceLevel', 'proposalsTier', 'skills',
+    'clientCountry', 'clientRating', 'publishedOn', 'url',
+];
+
+export const DETAIL_COLUMNS = [
+    'id', 'title', 'type', 'budget', 'experienceLevel', 'workload',
+    'category', 'skills', 'description',
+    'clientCountry', 'clientSpent', 'clientHires', 'clientRating',
+    'proposalsCount', 'publishedOn', 'url',
+];