@usequota/types

Shared TypeScript types for the Quota AI credit billing SDK.

Billing Model

All monetary values are stored in micro-dollars (1 unit = $0.000001, stored as BIGINT). To convert to USD: amount / 1_000_000.

Installation

npm install @usequota/types

Usage

import type { QuotaUser, CreditPackage } from "@usequota/types";

Balance semantics

The balance field on QuotaUser (and the /oauth/userinfo balance claim) can be number, null, or temporarily negative:

• null — the user is signed in via the Quota IdP but has not linked a credits wallet to this app. Surface a "Link wallet" affordance; do not display 0.
• Negative — a streaming completion's actual cost exceeded its pre-reservation. The pre-reservation still rejects new requests when balance is below the estimate, so a new request cannot start from a negative balance. The window is bounded by a single in-flight stream that under-estimated.

Types

• QuotaUser — authenticated user with balance (micro-dollars)
• CreditPackage — purchasable credit package (micro-dollars)
• QuotaSession — user session information for OAuth flows
• QuotaErrorResponse — standardized API error response-body shape (the class QuotaError lives in @usequota/core)
• ToolCall — tool/function call information
• ChatMessage — chat message in OpenAI-compatible format
• Tool — tool/function definition for function calling
• ChatCompletionRequest — chat completion request (multi-provider)
• QuotaMetadata — billing metadata in API responses (micro-dollars)
• ChatCompletionResponse — chat completion response with billing info

Contributing

Any change under src/ (except tests) requires a version bump in package.json. See agent/WORKFLOWS.md → SDK Versioning for semver guidance and the bump+publish sequence. A CI check fails any PR that touches src without bumping.

License

MIT