Convex component for treg.to that lets backend actions execute 3,000+ external tool endpoints with spend caps, audit logging, and hashed attribution.
npm install @listeningkit/tregA Convex component that wraps treg.to, a unified tool execution proxy providing access to 2,600+ external APIs (SpyFu, Firecrawl, SerpApi, GitHub, Stripe, Resend, and others) through a single authenticated endpoint. It runs inside Convex actions with per-call spend ceilings, SHA-256 hashed owner attribution, idempotency guarantees, and an isolated audit ledger stored in the component's own sandboxed database partition.
The @listeningkit/treg component stores your treg.to bearer token as a typed environment variable bound at the component level, so host action callers never pass secrets as function arguments. You instantiate a Treg client with components.treg and call treg.call(ctx, { endpoint, params, maxCostUsd }) from any Convex action.
The @listeningkit/treg component accepts a maxCostUsd field on every call. The treg.to proxy reads the X-Treg-Route-Max-Cost header and returns HTTP 402 before executing if the estimated cost exceeds the ceiling, so no funds are deducted. Each call result is logged to the component's isolated calls table keyed by hashed owner for per-user audit queries.
The treg.to catalog includes providers like SpyFu, SE Ranking, SerpApi, and Serpstat accessible via endpoint IDs such as spyfu.google.domain.competitors. Using @listeningkit/treg, you call treg.call(ctx, { endpoint: 'spyfu.google.domain.competitors', params: { domain } }) from a Convex action and implement failover to alternate providers on 429 or 503 responses.
The @listeningkit/treg component automatically writes a receipt to its internal calls table on every successful tool invocation, storing callId, ownerHash, endpoint, costMicro, servedVia, and timestamp. You query this ledger with treg.getCalls(ctx, { owner: identity.subject, limit: 20 }) from a Convex query function without any additional instrumentation.
@listeningkit/treg is a Convex component that adapts treg.to, an open-source tool execution proxy and registry, for use in Convex backends. It allows Convex actions to execute over 3,000 catalogued external API endpoints across 60+ providers through a single unified API with spend controls, idempotency guarantees, and an isolated audit ledger stored in the component's own database partition.
After installing @listeningkit/treg and registering it in convex/convex.config.ts with app.use(treg), set your bearer token using npx convex env set TREG_TOKEN='your-treg-team-token'. The component declares TREG_TOKEN as a typed environment variable in its convex.config.ts, so it is injected at the component boundary without requiring callers to pass it explicitly to action handlers.
No. @listeningkit/treg follows the Convex component specification and defines its own encapsulated schema.ts with a calls table. This table lives in the component's isolated database partition and has no access to or visibility into the host application's tables, so there is no risk of naming conflicts or data leakage.
The @listeningkit/treg component requires convex version 1.45.0 or higher as a peer dependency. This aligns with the Convex component specification version that introduced stable component authoring and isolated database partitions.
When calling treg.call(ctx, { maxCostUsd: 0.05, ... }), the component sets the X-Treg-Route-Max-Cost header on the outbound request to the treg.to proxy. If the proxy determines the estimated cost of executing the tool exceeds that ceiling, it returns HTTP 402 before executing the call, meaning no credits are deducted. This check happens upstream at treg.to, not client-side, making it a server-enforced guardrail.