feat(catalog): serve herus13 Apify actors on the platform key with capped billing

[JayZeeDesign]

Adds nine Apify tools (six Weibo modes, Google Maps, TikTok Shop, Lazada) and serves them — and the three Apify rows already in the catalog — on the platform key with billing bounded by Apify's own spend cap. Generic apify.web.scrape.job.start stays own-key only: its free price cannot meter an arbitrary actor.

Supersedes #641, #642, #643 and #644. This PR carries the code the rows need as well, so there is nothing to merge first.

Why the billing needed code

Every Apify per-result row settled at its estimate: run-sync-get-dataset-items answers a bare JSON array, which no settlement rule counted. Live runs also showed three things a per-row price alone cannot handle:

• maxItems does not bind pay-per-event actors whose own input sets the row count (maxItems=1 with body max_items: 3 returned and billed 3 rows). The run option Apify enforces on every billed event is maxTotalChargeUsd.
• A run stopping at its cap can bill one event it never pushed as a row (observed: 3 events, 2 rows).
• usageTotalUsd trails a finished run by minutes (0.00005 at SUCCEEDED, 0.01505 45 s later), so it cannot be settlement evidence.

What changed

Call path (application/call/resolve.py, settle.py)

• platform_request can pin queryParams.* singleton values; query values parse as plain ASCII only.
• An Apify per_result call on the platform key must send maxTotalChargeUsd (above 0, at most $1, at least call_fee + three rows) and timeout (at most 90 s, and 30 s under call_timeout_s, so the run and its rows arrive before any wait gives up). Only maxTotalChargeUsd, maxItems, memory and timeout are accepted, each once; dataset-view options (limit, format, unwind) are refused because they would make returned rows disagree with billed events.
• Hold = cap + cost.call_fee. Settlement = returned rows × row price + call_fee; within two rows of the hold, the hold (the caller's cap was reached).
• Own-key calls are untouched: no guard, no metering.

Catalog (apify.yaml)

• cost.call_fee (validated: Apify, per-result, USD) carries the per-run charge: Weibo start $0.00005 and Maps start $0.01 at pinned 1 GB, TikTok Shop two start events at its forced 2 GB ($0.004), LinkedIn jobs actor-start ($0.001 per job title × location searched: cost.call_fee_per names the body arrays that multiply the fee). Lazada has none: since the actor's 2026-09-25 pricing it bills no start event and no run compute to the caller.
• Pins on the platform key: memory and timeout for the new rows; TikTok Shop scrape_product_details: false plus body_allowlist (keeps the pricier product-detail event out); meta-ads enrichWithEcommerceData: false (an extra event per ad).
• LinkedIn jobs accepts only its declared body fields (body_allowlist, on every credential tier): the actor bills an actor-start per job title × location, which call_fee_per counts, and per geoIds entry, so geoIds is refused and places go in locations. Filters that do not multiply starts (company, industry, salary, workplace/employment/experience, Easy Apply) stay declared.
• Notes name maxTotalChargeUsd as the spend limit. Lazada's actor, since 2026-09-25, refuses caps below $0.05 and returns at least 10 products.

Routing (adapters.yaml)

• treg.google.serp.maps and treg.weibo.post.detail now include the Apify rows as candidates, the only two of these capabilities with a routing contract. The adapters fix the run's spend cap, timeout and memory so the child call passes the platform guard: Maps caps a routed call at 20 places (cap $0.25, no contact lookup), Weibo at one post (cap $0.05).

Tests and CI

• Async ownership tests (tests/test_asynctasks.py, tests/test_pinned_read_scope.py) now exercise Bright Data and CompanyEnrich, because apify.web.scrape.job.start no longer serves on the platform key; a new test proves it never reaches the relay.
• Frontend CI uploads Playwright traces and screenshots on failure.

Docs: docs/context/architecture/money.md ("Apify dataset-row settlement"), catalog.md.

Pricing on tiered actors

Google Maps, TikTok Shop and Meta ads price per Apify subscription tier. The catalog charges platform callers Apify's published default-plan (or, for Meta ads, BRONZE) rate, which is at or above what any paid plan pays, so the platform never bills below cost; own-key callers pay Apify directly at their own tier. This is deliberate list pricing, not an error.

Residual loss, bounded

A run that times out, fails or aborts answers 400 with no rows and releases; so does a caller disconnect or an answer over the 8 MiB evidence limit. Apify may still have billed events up to the cap, so the platform absorbs at most $1 per such call. Billing a timed-out run at the hold was tried and reverted: a run that timed out after its start event cost $0.00005 and would have billed the whole cap.

Operator precondition: the Apify account behind the platform key must keep general resource access Restricted. The 400 body names the run, and with public access anyone could read that unbilled run's dataset by id.

Evidence

Prices, 2026-09-26: every Apify per-result row's test_request ran on the platform key and Apify's chargedEventCounts matched its rate card; all twelve rows are now source: observed, confidence: verified.

Row	Events billed	Apify charge
Weibo (6 modes)	1 row event + start	$0.00505 each
Google Maps	1 place + start	rate-card price for the key's tier
TikTok Shop	1 search result + 2 starts at 2 GB	rate-card price for the key's tier
Lazada	10 products (the actor's floor)	$0.05, no platform usage
Meta ads	1 ad	rate-card price for the key's tier
TikTok ads	1 ad	$0.003
LinkedIn jobs	1 job + actor-start; 3 titles → 3 jobs + 3 actor-starts	$0.002; $0.006 (treg billed $0.006)

TikTok ads was marked upstream-broken (empty datasets); it returns rows again and is verified with a captured example. Routed calls through the adapters: treg.google.serp.maps returned 20 places and billed $0.19; treg.weibo.post.detail returned the post and billed $0.00505.

Live on the Apify API:

• Rate cards (pricingInfos) match every row's price, event and start fee.
• Through a local server on the platform key, all twelve Apify per-result rows returned 201 and settled at rows × price + fee; in every run the caller was billed at least what Apify charged (e.g. Weibo $0.00505 vs $0.00505, a capped Weibo run $0.02005 vs $0.01505).
• Refused before relay: missing cap, cap above $1 or below three rows, limit, format=csv, non-ASCII digits, repeated keys, timeout over 90, meta-ads enrichment on, LinkedIn geoIds, TikTok Shop product_urls/detail mode.

Reviewed in independent rounds with live verification; each blocking finding was fixed and re-reviewed.

Validation

• Catalog validator: no Apify errors (the three openrouter.ai-judge.decide errors are on main).
• Import contracts: 14 kept.
• Full suite: the same 13 failures as main (dashboard assets not built locally, hub, MCP OAuth, referrals, SEO, single-user); no failures specific to this branch.

Follow-ups

• TikTok ads: an undeclared only_total returns one free count row that settlement bills as a result (caller overpays $0.003; no platform loss). Declare it or allowlist the row.

• Settle failed runs exactly from chargedEventCounts through a deferred settle.

• A reconcile check that each custom-event actor still bills one event per returned row.

• Accept an absent pinned field when the actor default equals the pin.

🤖 Generated with Claude Code