feat(catalog): add GetLeads.io contact data and shared trial

[shehjad-dev]

Adds GetLeads.io (getleadsio) as a pasted-Bearer-key enrichment provider with 12 curated direct tools. Every tool works with either a team's own key or treg's platform key.

Why now: GetLeads.io provides contact search, company-contact discovery, person enrichment, phone lookup, and funding and acquisition signals through one API. Its promotional credits let treg measure demand before it buys a paid plan. GetLeads.io does not publish a normal USD replacement price per database credit, so this PR does not invent one.

No external vendor contact is required. The platform credential uses an existing promotional account. No key, personal data, raw response, or absolute account balance appears in this PR.

What's in the diff

• oauth_providers.py / config.py — standard pasted-key provider and optional platform slot; Authorization: Bearer …; free GET /api/v1/usage/fair-use verification probe
• catalog/getleadsio.yaml — 12 original, live-verified provider operations with sanitized response fixtures; no artificial .trial tools
• all 12 tools support BYOK and platform calls; a team's own key wins and is never metered by treg
• callers control all provider-valid page limits, batch sizes, offsets, and filters; treg does not insert, reduce, or rewrite them
• fx.yaml — exact $0, kind: treg_trial, and five successful credit-using platform calls per team per UTC day
• free search-count and filter-discovery calls do not consume the trial allowance
• the allowance counts calls, not returned records or GetLeads.io credits; one successful call can use zero to thousands of promotional credits
• the shared trial check now counts only successful platform-tier calls whose catalog cost is not free; failed calls, free tools, and BYOK history do not consume a platform trial
• the existing shared capacity guard returns a typed 503 with an own-key instruction after a capacity sweep observes zero; BYOK remains available
• capacity collector and policy — read numeric credits_remaining from the free fair-use route and apply the documented 100 requests/minute platform-key limit
• no global safety floor and no automatic top-up
• no routing adapter or Enrich Arena membership: reserved invalid enrichment inputs returned success=true and consumed credits, so treg cannot define a reliable provider-neutral hit or miss
• no CSV upload, asynchronous export, profile monitoring, internal health, or account-usage catalog tools
• supplied GetLeads logo, regenerated skill mirrors, provider/context documentation, and connection, catalog, capacity, BYOK, and platform-trial tests

Endpoint access and cost

Every listed tool supports both credential paths. BYOK calls use the team's GetLeads.io plan and cost $0 from its treg balance. Platform calls use treg's GetLeads.io account and also cost $0 from the team's treg balance during this trial.

tool	GetLeads.io credit rule on the platform account
getleadsio.people.enrich.from_email	1 credit per successful item; up to 100 input items
getleadsio.people.enrich.from_linkedin	1 credit per successful item; batch and per-item limits are caller-controlled
getleadsio.people.enrich.from_person	1 credit per successful item; up to 100 input items
getleadsio.people.phone.lookup	1 credit when a match is returned
getleadsio.people.phone.lookup_batch	1 credit per successful item; batch and per-item limits are caller-controlled
getleadsio.people.colleagues	1 credit per returned record; limit_per_item accepts 1–5,000
getleadsio.people.decision_makers	1 credit per returned record; limit accepts 1–5,000
getleadsio.people.search	1 credit per returned record; limit accepts 1–5,000
getleadsio.people.search.count	free upstream; does not consume a trial slot
getleadsio.people.search.filters	free upstream; does not consume a trial slot
getleadsio.companies.funding.feed	1 credit per returned record; limit accepts 1–200
getleadsio.companies.acquisitions.feed	1 credit per returned record; limit accepts 1–200

Verification evidence ledger

Live checks used synthetic inputs and retained only sanitized shapes plus relative credit movement.

route / check	HTTP	observed credit effect	catalog decision
fair-use, bogus key	401	none	rejects a bad pasted key
fair-use, valid key	200	none	connection probe and capacity source
contact search count	200	0	original free tool supports BYOK and platform
filter values	200	0	original free utility supports BYOK and platform
contact search, two one-row pages	200	1 credit each	original tool supports BYOK and platform; caller controls limit
contact search, zero-row miss	200	0	native response is relayed
single phone lookup, synthetic miss	200	0	original tool supports BYOK and platform
phone batch, synthetic miss	200	0 in this check	original tool supports BYOK and platform; caller controls batch size
colleagues / decision makers, zero-row synthetic misses	200	0	original tools support BYOK and platform; caller controls limits
email / LinkedIn / person enrichment, reserved-invalid inputs	200	1 credit each	direct tools only; no routed adapter
funding feed, limit=1	200	1 credit	original tool supports BYOK and platform; documented maximum is 200
acquisition feed, limit=1	200	0	original tool supports BYOK and platform; documented maximum is 200

Verification

• catalog validator: 105 provider file(s), 3377 endpoint(s), 0 error(s), 0 warning(s)
• complete relevant trial, capacity, and catalog regression set: 611 passed
• full isolated parallel suite: 4232 passed, 8 skipped
• supplied-logo and provider checks: 16 passed
• import-linter: 14 contracts kept, 0 broken
• platform runtime test: getleadsio.people.search accepts limit=5000, uses the platform Bearer key, preserves the request value, and does not move the treg balance
• BYOK priority test: the same platform-eligible search tool uses the team's key and remains unmetered when both keys are available
• trial tests: free tools do not consume trial slots, remain available after the paid-call allowance, and old BYOK rows do not consume a later platform trial
• zero-capacity test: a published zero refuses the platform call before reserve with a typed 503 and an own-key instruction; the same request succeeds with BYOK
• context drift: all changed documented sources map to reviewed fragments; no gaps

What was not verified

• The live platform account was not exhausted to manufacture an insufficient-credit response.
• The exact upstream response on the call that exhausts the account is unknown. The clear typed 503 starts after the capacity sweep observes zero.
• Large live searches, large batches, and 5,000-record platform calls were not run. Their accepted ranges come from the documented request contract; the relay-preservation test uses a local upstream echo.
• GetLeads.io Unlimited-plan fair-use responses were not verified. The current collector supports the promotional credit response with numeric credits_remaining.
• No reliable miss contract was found for routing or Enrich Arena.

Ops

• Set TREG_PLATFORM_KEY_GETLEADSIO only in the serving environment and add getleadsio to TREG_PLATFORM_PROVIDERS to enable the trial. BYOK remains available without either setting.
• Do not configure automatic top-up for the promotional account.
• Monitor the remaining promotional credits. If usage appears or the pool is exhausted, decide whether to buy a suitable plan.
• After purchase, verify the plan's fair-use response and decide whether platform access stays free or uses a treg-set USD price. A flat subscription does not establish a vendor price per database credit.
• No provider-specific overflow route or upstream exhaustion response is claimed.

Review focus

• Is it acceptable that all 12 original tools use the same BYOK and platform request contract?
• Is the temporary $0, five-credit-using-call policy acceptable when one call can use many GetLeads.io credits?
• Is the shared rule correct that free tools, failures, and BYOK history do not consume a platform trial allowance?
• Is the zero-capacity behavior clear enough when the exact upstream exhaustion response remains unverified?
• Is excluding GetLeads.io from routing and Enrich Arena correct until a reliable provider-neutral miss rule exists?