credits

Methods and types of the `credits` namespace (`client.credits` / `bot.credits`).

Interfaces

GetBalanceResponse

Properties

Property	Type	Description
`balance`	`number`	Total spendable balance — sum of planBalance + purchasedBalance.
`hasPriorTopUp?`	`boolean`	True when the workspace has at least one prior manual top-up (a `subscriptionGrant` order). Auto top-up can only be enabled once this is true — users must top up manually once first.
`planBalance`	`number`	Plan-granted credits for the current billing cycle. Refreshed (SET, not added) on every Stripe renewal. Unspent plan credits do NOT carry over.
`purchasedBalance`	`number`	Purchased credits — accumulated from one-off top-ups, auto-top-ups, admin grants. Carries over indefinitely.

UsageReportIntegrationRow

Properties

Property	Type
`billedCredits`	`number`
`callCount`	`number`
`integrationPoint`	`string`

UsageReportParams

Properties

Property	Type	Description
`endDate?`	`string`	ISO date string. Server defaults to "now" when omitted.
`integrationPoint?`	`string`	Narrow the per-user breakdown to a single integration point.
`startDate?`	`string`	ISO date string. Server defaults to 30 days ago when omitted.
`userId?`	`string`	Narrow the per-integration breakdown to a single user's calls.

UsageReportResponse

Properties

Property	Type
`byIntegration`	`UsageReportIntegrationRow`[]
`byUser`	`UsageReportUserRow`[]
`filters`	{ `endDate`: `string`; `integrationPoint`: `string` \| `null`; `startDate`: `string`; `userId`: `string` \| `null`; }
`filters.endDate`	`string`
`filters.integrationPoint`	`string` \| `null`
`filters.startDate`	`string`
`filters.userId`	`string` \| `null`
`total`	{ `billedCredits`: `number`; `callCount`: `number`; `tokensIn`: `number`; `tokensOut`: `number`; }
`total.billedCredits`	`number`
`total.callCount`	`number`
`total.tokensIn`	`number`
`total.tokensOut`	`number`

UsageReportUserRow

Properties

Property	Type
`avatar`	`unknown`
`billedCredits`	`number`
`callCount`	`number`
`color`	`string` \| `null`
`displayName`	`string` \| `null`
`userId`	`string`

Functions

default()

function default(client): {
  getBalance: Promise<GetBalanceResponse>;
  getUsageReport: Promise<UsageReportResponse>;
};

Service-agnostic Nurama Credit balance + usage endpoints.

The /v1/credits/* route shape and SDK namespace are deliberately decoupled from any single service's naming so future services (convos, etc.) can draw from the same balance without callers having to know where the spend originated. Today the metered data is AI-only because AI is the only service that's metered, but the contract is stable.

Parameters

Parameter	Type
`client`	`default`

Returns

Name	Type	Description
`getBalance()`	(`workspaceId`) => `Promise`<`GetBalanceResponse`>	Get the workspace's spendable credit balance.
`getUsageReport()`	(`workspaceId`, `params?`) => `Promise`<`UsageReportResponse`>	Get the workspace's credit usage report. Same shape as the AI usage report — today the data is AI-only because AI is the only service that's metered.

On this page