---
name: bijection-neutralcost
description: "Evaluate and integrate the Neutral Cost component with Bijection."
---

# Neutral Cost

Organizes all of your costs into one place. Seamlessly track your AI usage and Tool costs and charge accordingly.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: neutral-cost
- Source: https://github.com/neutralbase/neutral-cost
- npm: https://www.npmjs.com/package/neutral-cost
- Directory: https://bijection.com/components/neutralcost

Read the upstream README for setup, license, and compatibility before using it.

## 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 neutral-cost. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Neutral Cost

## Instructions

Neutral Cost provides comprehensive cost tracking and billing management for AI applications built on Convex. It tracks token usage from AI providers like OpenAI, tool costs from services like web search APIs, and applies configurable markup multipliers for customer billing. The component includes rate limiting capabilities and credit-based billing to help developers understand profitability and build sustainable business models.

### Installation

```bash
npm install neutral-cost
```

## Use cases

- **Track AI model costs per customer** to understand which users are profitable and identify high-usage accounts that need pricing adjustments
- **Implement tiered usage models** where customers get premium model access up to a limit, then fall back to cheaper models to maintain profitability
- **Build prepaid credit systems** with configurable markup multipliers across different AI providers and models for flexible billing
- **Monitor tool usage costs** from external APIs like search, image generation, or data enrichment services alongside AI model costs
- **Export detailed cost analytics** to frontend dashboards for customer usage insights and billing transparency

## How it works

The component integrates into your Convex app through the `convex.config.ts` file and provides a `CostComponent` class that wraps cost tracking functionality. You call `addAICost()` and `addToolCost()` from Convex actions to log usage with token counts, provider details, and user context.

Cost calculation uses a pricing database that maps model IDs and tool IDs to their actual costs, then applies optional markup multipliers configured per provider, model, or tool. These multipliers can be set in code or stored in the database for runtime updates.

The component exposes query functions like `getAICostsByThread()` and `getTotalAICostsByUser()` that you can export through your own Convex functions to power frontend cost displays. All cost data is organized by user, thread, and message for granular tracking and billing.

## 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 Neutral Cost is not needed

## Resources

- [npm package](https://www.npmjs.com/package/neutral-cost)
- [GitHub repository](https://github.com/neutralbase/neutral-cost)
- [Convex Components Directory](https://www.convex.dev/components/neutralcost)
- [Convex documentation](https://docs.convex.dev)