# Usage and direct provider calls

Read advisory capacity or account for a premium call without a model adapter.

Use `@enlitt/sdk/core` when you need session helpers, typed errors, usage
information, or premium accounting without a Vercel or OpenAI model adapter.
It is framework-neutral and server-only.

## Read current capacity with usage()

Inside session middleware:

```ts
import { usage } from "@enlitt/sdk/core";

const { standard, premium } = await usage();
// remainingPercent: integer percentage of available capacity.
// limitCapNanoUsd: canonical NANOUSD string for the current single-call cap.
console.log(standard.remainingPercent, premium.limitCapNanoUsd);
```

Outside middleware, pass `{ session }`. Both forms also accept `secretKey`
and `baseUrl`, like a model call. The helper authenticates with your model
key and the user's personal session. It creates no call and reserves nothing.

The result is **advisory**: another request can consume capacity immediately
after the read. Only admission decides whether a call may proceed. Unlimited
standard capacity reports 100%. The result includes no plan, balance, credit
units, period, or limits object.

## Account for a direct premium provider call

`withPremiumCharge()` wraps one model operation you run yourself. It admits
the operation first, executes your callback, then reports the terminal outcome.
This example accepts your provider call as a callback:

```ts
import { withPremiumCharge } from "@enlitt/sdk/core";

export async function runPremium<T>(
  provider: { id: string; model: string },
  callProvider: () => Promise<T>
): Promise<T> {
  return withPremiumCharge({ provider, maxCharge: "10000000" }, async (charge, operation) => {
    const result = await callProvider();
    charge("5000000");
    // operation.effectiveMaxChargeNanoUsd is the admitted maximum.
    return result;
  });
}
```

Run it inside session middleware or supply an explicit `session`. The
`provider` labels must describe the provider and model you actually call.
Enlitt does not configure or invoke that provider for you.

`charge(amount)` records the intended charge; the last amount wins. Calling
it zero times charges zero. A failed callback charges zero regardless of prior
`charge()` calls. Completion and cancellation use the last charge, capped at
`operation.effectiveMaxChargeNanoUsd`. Pass `signal` when you need cancellation
and use it in your provider call too.

A loop of provider calls needs a loop of `withPremiumCharge()` operations.
See [Models and pricing](/docs/models.md) for integer amounts and reporting,
[Spending limits](/docs/premium-limits.md) for caps, and
[Idempotency](/docs/idempotency.md) for retry identities.