mirror of https://github.com/simstudioai/sim.git synced 2026-09-21 13:00:04 +08:00

Files

T

Waleed 918ba8a86a feat(ahrefs): validate integration, fix cents/column bugs, add 13 v3 endpoints (#5447 )

* feat(ahrefs): validate integration, fix cents/column bugs, add 13 v3 endpoints

Audited the existing Ahrefs integration against live API v3 docs and fixed
real bugs: broken_backlinks selected the wrong column (http_code_target
instead of http_code), and keyword_overview/metrics/metrics_history returned
CPC/cost fields in USD cents without converting to USD. Also fixed the
top-pages mode dropdown missing the "exact" option.

Added 13 new tools covering previously-unsupported Ahrefs v3 endpoints:
Rank Tracker (overview, SERP overview, competitors overview, competitors
stats), Batch Analysis, Site Audit page explorer, four history/trend
endpoints (domain rating, metrics, referring domains, keywords), Related
Terms, Anchors, and Paid Pages.

Note: the CPC/cost unit fix silently shifts existing organicCost/paidCost/cpc
values by 100x for any workflow already consuming them (the old values were
wrong, in cents instead of dollars).

* fix(ahrefs): convert remaining cents-to-USD fields, drop unneeded fallback key

Rank Tracker SERP Overview's value field, Competitors Stats' trafficValue,
and Competitors Overview's nested competitor value were all left in USD
cents while every other monetary field in the integration converts to USD
- fixed for consistency with the rest of the integration.

Also drops the unverified `data.results` fallback in Batch Analysis; the
Ahrefs v3 docs confirm the response key is always `targets`.

* docs(ahrefs): regenerate docs to reflect cents-to-USD conversion fix

The generated docs page was stale after the previous commit converted
rank_tracker_serp_overview.value, rank_tracker_competitors_stats.trafficValue,
and rank_tracker_competitors_overview's nested value from cents to USD -
regenerating picks up the corrected field descriptions.

* fix(ahrefs): revert incorrect broken_backlinks column, fix missed top_pages conversion, revert unverified competitor value conversions

Independent re-verification against live Ahrefs v3 docs surfaced two real
regressions from the earlier fix rounds and one missed conversion:

- broken_backlinks: the earlier fix changed the selected column from
  http_code_target to http_code, but the docs say http_code is the
  *referring page's* status and http_code_target is the *broken target
  page's* status - the tool needs the latter (matches its own output
  description). Reverted to http_code_target.
- top_pages: value field was never divided by 100 despite the docs stating
  it's in USD cents and the output already claiming USD - fixed.
- rank_tracker_competitors_stats.trafficValue and the nested competitor.value
  in rank_tracker_competitors_overview were converted from cents to USD last
  round on a "match every other monetary field" assumption, but the live docs
  do not document these two fields as cents (unlike every field that was
  correctly converted). Reverted to passthrough and dropped the "(USD)"
  claim from their descriptions until Ahrefs documents the unit.

Also added the missing "exact" mode option to top_pages' mode param
description, matching every sibling tool.

* fix(ahrefs): convert rank tracker competitor value/trafficValue to USD

Both bots independently flagged these two fields as inconsistent with
every other monetary field in the integration, all 7 of which are
explicitly documented as USD cents. Neither field has explicit unit
documentation (one is undocumented as cents, the other's schema isn't
statically retrievable at all), but given the unanimous pattern across
every other verified field and no contrary evidence, converting for
consistency is the better bet than leaving them as an outlier.

* style(ahrefs): drop non-TSDoc inline comments introduced in this PR

Repo convention disallows non-TSDoc comments; removed the three
explanatory // comments this PR added next to cents-to-USD conversions
(keyword_overview, paid_pages, related_terms) - pre-existing comments
elsewhere in the file are untouched, out of scope for this PR.

* fix(ahrefs): default optional country to us consistently across all tools

paid_pages, metrics_history, keywords_history, and batch_analysis were the
only 4 of the 11 tools with an optional country param that didn't fall back
to "us" when omitted, unlike domain_rating, metrics, keyword_overview,
organic_keywords, organic_competitors, top_pages, and related_terms - all
of which default client-side. Aligned all four to the same convention so
direct tool/agent calls without an explicit country get the same behavior
regardless of which operation is used.

* fix(ahrefs): split shared date subBlock id for datetime-format operations

site_audit_page_explorer and rank_tracker_serp_overview both reused the
generic 'date' subBlock id with YYYY-MM-DDThh:mm:ss semantics, while every
other operation using that same id expects YYYY-MM-DD. Switching operations
without clearing the field could carry a stale wrong-format value into the
new operation's request. Split into distinct ids (crawlDate, asOfDate)
mapped back to each tool's date param in tools.config.params.

2026-07-06 16:07:03 -07:00