@unprice/budgets is the budget client on its own. @unprice/api includes it and re-exports its
handles, errors, and types, so code moves between the two packages by changing the import, and
instanceof checks match errors from either.
Operations
unprice.budgets calls the API directly. Each method returns { result } or { error }. Check
error before you use result.
The request and response schemas are in the API reference.
Handles
unprice.budget(key) returns a handle bound to one key. It never creates or changes the budget.
Each method except
spend can also return { error }. A hold from authorize has id, key,
amount, expiresAt, settle({ amount }), and release(). See
spend against a budget.
spend input
string | number
required
The most the work may use, in the budget’s unit.
spend authorizes this amount before fn runs.string
A stable key for this operation, such as the request id. When you omit it,
spend generates one
and puts it on its errors as error.idempotencyKey.integer
How long the hold stays open. Defaults to the budget’s
holds.defaultTtlMs.fn receives the hold and returns { value, actual }. spend settles actual, which may not
exceed estimate, and returns value.
Local handles
unprice.budget(key, { mode: "local", lease }) returns a local handle. It
has the same members, plus mode: "local", flush(), and close(). unprice.close() returns
every open lease. It resolves with a { key, error } for each lease it could not return.
Amounts accept numbers or decimal strings and come back as decimal strings. Numbers are rounded to
8 decimal places.
Errors
Errors and recovery explains each one.
Client options
string
required
A project API key. Use a runtime key where the code spends, and a config key only where caps are
raised.
string
default:"https://api.unprice.dev"
Send requests to your own Unprice deployment.
{ attempts?: number; backoff?: (retryCount: number) => number }
Retries on network and server errors.
attempts defaults to 2, so a call makes at most three
requests.(promise: Promise<unknown>) => void
Keeps a serverless runtime alive after the response. With it,
spend returns once your function
finishes and settles in the background.(error: BudgetSettleError) => void
Receives a background settle that failed. Its hold stays open and counts its full estimate when
it expires.
(input: Request) => Promise<Response>
A custom
fetch for non-standard runtimes or tests.Record<string, string>
Additional headers to send with each request.
RequestCache
default:"no-store"
The
fetch cache mode.boolean
default:"false"
Log retry attempts with
console.debug.boolean
default:"false"
Stop sending anonymous telemetry: runtime, platform, and SDK version.