---
name: bijection-treg
description: "Evaluate and integrate the Treg component with Bijection."
---

# Treg

Production Bijection component for treg.to — the OpenRouter for developer tools. Run, route, and pay for 3,000+ catalogued endpoints across 60+ providers through one API and CLI.

- Package: @bijectionhq/treg
- Category: AI & Agents
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/treg/tree/fac7dc148c0e0411a224f1c24bc33087133370c6
- Upstream: https://github.com/matthewdonsemail-lab/convex-treg/tree/9896d556b30f3b832650624fb74481025c86e0eb
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/treg

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/treg.git
cd treg
git checkout fac7dc148c0e0411a224f1c24bc33087133370c6
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @listeningkit/treg. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses treg. Follow the installation and configuration steps exactly.

# treg

## Instructions

Use treg to convex component for treg.to that lets backend actions execute 3,000+ external tool endpoints with spend caps, audit logging, and hashed attribution. This Convex component integrates directly with your backend.

### Installation

```bash
npm install @listeningkit/treg
```

Current npm version: `@listeningkit/treg@0.1.4`

### Capabilities

- Execute 3,000+ catalogued API endpoints across 60+ providers from Convex actions without managing per-provider credentials on the client
- Enforce per-call spend ceilings that cause treg.to to reject requests upfront before any funds are charged
- Store automatically isolated spend receipts in a sandboxed component database that never conflicts with host application schema
- Attribute tool usage to individual users via server-side SHA-256 hashed owner IDs without leaking PII to upstream providers

## Examples

### how to call external APIs from Convex actions without exposing credentials

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.

### how to add per-user spend limits on external tool calls in Convex

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.

### how to run SEO or SERP data tools inside a Convex AI agent workflow

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.

### how to audit external API usage per user in a Convex backend

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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by treg is not needed

## Troubleshooting

**What is @listeningkit/treg and what does it do?**

@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.

**How do I configure the treg.to API token in a Convex project?**

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.

**Does @listeningkit/treg conflict with my existing Convex database schema?**

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.

**What version of Convex is required to use @listeningkit/treg?**

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.

**How does the spend ceiling work and what happens if a call exceeds it?**

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.

## Resources

- [npm package](https://www.npmjs.com/package/%40listeningkit%2Ftreg)
- [GitHub repository](https://github.com/matthewdonsemail-lab/convex-treg)
- [Live demo](https://tremendous-seahorse-330.convex.site)
- [Convex Components Directory](https://www.convex.dev/components/listeningkit/treg)
- [Convex documentation](https://docs.convex.dev)