mbase-sdk 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,717 @@
+type MeterbaseOptions = {
+    /** A secret key. It names its own workspace. */
+    apiKey: string;
+    /** Defaults to the hosted engine. */
+    baseUrl?: string;
+    /** Per attempt, not per call. */
+    timeout?: number;
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+};
+type RequestOptions = {
+    signal?: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+};
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+type Request = RequestOptions & {
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Replay this call even though its method is not safe. Only a route that
+     * carries an idempotency key may set it, and the key has to be fixed before
+     * `request` is called — the loop re-sends one body, so a key generated
+     * per attempt would count the same usage twice.
+     */
+    idempotent?: boolean;
+};
+declare class Client {
+    #private;
+    constructor(options: MeterbaseOptions);
+    request<T>(req: Request): Promise<T>;
+}
+
+/** Enveloped so pagination can arrive without breaking callers. */
+type List<T> = {
+    data: T[];
+};
+type Meter = {
+    id: string;
+    workspace_id: string;
+    key: string;
+    name: string;
+    description: string;
+    unit: string;
+    value: string;
+    /** Usage-alert percents for this meter. `null` inherits the workspace's
+     * defaults; `[]` turns alerts off for the meter. A customer's own list
+     * beats this one. */
+    thresholds: number[] | null;
+    created_at: string;
+    updated_at: string;
+    archived_at: string | null;
+};
+type MeterCreateParams = {
+    key: string;
+    name: string;
+    description?: string;
+    unit?: string;
+    value?: string;
+    /** Whole percents, 1–1000, at most 32 of them; a mark over 100 is an
+     * overage alert. Omitted, the meter inherits the workspace's. */
+    thresholds?: number[];
+};
+/**
+ * An omitted field is left alone; `""` clears an optional one.
+ *
+ * `thresholds` is the exception on both counts: `null` is a value there, not
+ * silence. Omit it to keep the stored list, send `null` to inherit the
+ * workspace's again, send `[]` to turn alerts off for this meter.
+ */
+type MeterUpdateParams = {
+    key?: string;
+    name?: string;
+    description?: string;
+    unit?: string;
+    value?: string;
+    thresholds?: number[] | null;
+};
+type MeterListParams = {
+    include_archived?: boolean;
+};
+type Customer = {
+    id: string;
+    workspace_id: string;
+    external_id: string;
+    name: string;
+    metadata: Record<string, unknown>;
+    /** Usage-alert percents for this customer. `null` inherits — the meter's
+     * list, then the workspace's. `[]` turns alerts off for this customer.
+     * The most specific of the three, and it always wins. */
+    thresholds: number[] | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+};
+/**
+ * A plan as a customer read embeds it: the plan itself, flattened onto the
+ * assignment that named it.
+ *
+ * `id` is the **plan's**. The assignment's own id is on
+ * `customers.plan.retrieve`, which is where instructions are identified;
+ * what a reader wants from an embed is which plan. `cycle` is here because
+ * `anchor_at` fixes a period only alongside its stride.
+ */
+type EmbeddedPlan = {
+    id: string;
+    key: string;
+    name: string;
+    cycle: PlanCycle;
+    /** When this instruction takes effect — ahead of now on `pending_plan`. */
+    effective_at: string;
+    /** What the customer's periods are measured from. */
+    anchor_at: string;
+    effective: ApplyMode;
+    reconciliation: RecordedReconciliation;
+};
+/**
+ * A single-customer read. The plan travels with the customer because a caller
+ * holding one almost always goes on to ask what it is entitled to.
+ *
+ * `plan` is the one in force now and `pending_plan` the change waiting to
+ * land, each `null` when there is none — holding no plan is a default deny,
+ * not a failure. `customers.list`, `create`, `update` and `delete` answer a
+ * plain `Customer`: a listing does not embed, where the same read would run
+ * per row for an answer most callers of a list do not want.
+ */
+type CustomerWithPlan = Customer & {
+    plan: EmbeddedPlan | null;
+    pending_plan: EmbeddedPlan | null;
+};
+type CustomerCreateParams = {
+    external_id: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    /** Whole percents, 1–1000, at most 32 of them; a mark over 100 is an
+     * overage alert. Omitted, the customer inherits. */
+    thresholds?: number[];
+};
+/**
+ * An omitted field is left alone. `external_id` cannot be cleared, and
+ * `metadata` is replaced wholesale rather than merged.
+ *
+ * `thresholds` reads `null` as a value, not as silence: omit it to keep the
+ * stored list, send `null` to go back to inheriting the meter's or the
+ * workspace's, send `[]` to turn alerts off for this customer alone.
+ */
+type CustomerUpdateParams = {
+    external_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    thresholds?: number[] | null;
+};
+type CustomerListParams = {
+    include_deleted?: boolean;
+};
+/** `customer_id` is the tenant's own external id and `meter_id` the meter's
+ * key: an SDK never holds Meterbase uuids. */
+type CheckParams = {
+    customer_id: string;
+    meter_id: string;
+    /** What is about to be consumed, `1 … 100000000000`. Defaults to `1`, which
+     * asks whether there is any capacity at all. */
+    quantity?: number;
+};
+type CheckResult = {
+    allowed: boolean;
+    /** Unlimited for this meter. `available` is `null`. */
+    no_cap: boolean;
+    /**
+     * The whole capacity: the plan's unused entitlement for the current period,
+     * floored at 0, plus every open grant. `null` under `no_cap`, where capacity
+     * is not a number.
+     *
+     * One figure and no breakdown: `check` answers from a single cached integer,
+     * and itemising where the capacity came from would cost it that. For the
+     * per-grant detail, read `customers.allowances.list`.
+     */
+    available: number | null;
+};
+/**
+ * `track` records work that already happened, so it never refuses on capacity
+ * — the gate is `check`, which runs before the work. A quantity beyond the
+ * customer's capacity is recorded, drives `available` to 0, and the next
+ * `check` says no.
+ */
+type TrackParams = {
+    customer_id: string;
+    meter_id: string;
+    /** Integer, `1 … 100000000000`. Defaults to `1`, which is what a counting
+     * meter sends. */
+    quantity?: number;
+    /**
+     * The engine requires one; the SDK generates one per call when it is
+     * omitted, and reuses it across that call's retries. Supply your own when
+     * the caller already has an id for the work — a job id, a request id — so a
+     * retry from further out replays rather than counts twice.
+     */
+    idempotency_key?: string;
+};
+/** Enveloped, like the list reads, so the receipt can grow a sibling field
+ * without breaking callers. */
+type TrackResult = {
+    event: UsageEvent;
+};
+/**
+ * A receipt. The same shape whether the event is new or a replay — no capacity
+ * figures, no nullable fields, nothing to branch on.
+ */
+type UsageEvent = {
+    /** Meterbase's id for the event. A retry of the same key returns this same
+     * id. */
+    id: string;
+    customer_id: string;
+    meter_id: string;
+    quantity: number;
+    /** When Meterbase stored it, which chooses the period the event counts
+     * against. */
+    occurred_at: string;
+    /** The same instant as `occurred_at`. Both are on the wire so a reader of
+     * either keeps working. */
+    recorded_at: string;
+    idempotency_key: string;
+    /** `true` when this key had already been recorded: nothing was written, and
+     * this is the original event. */
+    replayed: boolean;
+};
+/**
+ * A plan's billing period. Every recurring allowance it holds is measured
+ * against it, and it is fixed when the plan is created. `one_time` is not
+ * among them: that is a kind of allowance, not a period.
+ */
+type PlanCycle = "daily" | "weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly";
+type Plan = {
+    id: string;
+    workspace_id: string;
+    key: string;
+    name: string;
+    description: string;
+    cycle: PlanCycle;
+    created_at: string;
+    updated_at: string;
+    archived_at: string | null;
+};
+type PlanCreateParams = {
+    key: string;
+    name: string;
+    description?: string;
+    cycle: PlanCycle;
+};
+/**
+ * An omitted field is left alone; `""` clears the description. There is no
+ * `cycle`: moving a plan's period would re-date every period its customers
+ * were already measured against, so a different cadence is a different plan.
+ */
+type PlanUpdateParams = {
+    key?: string;
+    name?: string;
+    description?: string;
+};
+type PlanListParams = {
+    include_archived?: boolean;
+};
+/**
+ * Which of a `(plan, meter)` pair's two lineages a version belongs to. Each
+ * numbers itself separately.
+ */
+type PlanAllowanceKind = "recurring" | "one_time";
+type ApplyMode = "immediate" | "next_cycle";
+/**
+ * What an `immediate` plan change does with the period it lands in: `none`
+ * lets the new plan's amount govern the whole period, `prorate` weights the
+ * two plans by the fraction each was held for, and `reset` closes the period
+ * at the change and opens a fresh one — moving the customer's anchor, and so
+ * their renewal day.
+ */
+type Reconciliation = "none" | "prorate" | "reset";
+/**
+ * Reconciliation as a stored row may read it. The plan history is append-only,
+ * so a mode the API has since stopped accepting — `rebalance` — survives in
+ * rows written while it did. Responses widen to this; requests do not.
+ */
+type RecordedReconciliation = Reconciliation | "rebalance";
+/**
+ * How long a one-time grant lives once minted. Months are kept apart from
+ * days because they are not the same length: three months from Jan 31 dies
+ * Apr 30, ninety days dies May 1.
+ */
+type Validity = {
+    months: number;
+    days: number;
+};
+type PlanAllowance = {
+    id: string;
+    workspace_id: string;
+    plan_id: string;
+    meter_id: string;
+    /** 1, 2, 3… per lineage. Assigned by the engine, never by the caller. */
+    version: number;
+    /** Units per period. `0` is legal and grants nothing. `null` under no_cap. */
+    amount: number | null;
+    no_cap: boolean;
+    kind: PlanAllowanceKind;
+    /** `one_time` only; `null` is a grant that never expires. */
+    valid_for: Validity | null;
+    effective_from: string;
+    apply_mode: ApplyMode;
+    created_at: string;
+};
+/**
+ * An allowance says how much, never how often: the period is the plan's
+ * cycle. Give exactly one of `amount` or `no_cap`.
+ */
+type PlanAllowanceSetParams = {
+    meter_id: string;
+    amount?: number;
+    no_cap?: boolean;
+    /** Defaults to `recurring`. */
+    kind?: PlanAllowanceKind;
+    /** `one_time` only. */
+    valid_for?: Validity;
+    /** Defaults to `next_cycle`, except `one_time` which is always immediate. */
+    apply_mode?: ApplyMode;
+};
+type PlanAllowanceListParams = {
+    meter_id?: string;
+};
+type Assignment = {
+    id: string;
+    workspace_id: string;
+    customer_id: string;
+    plan_id: string;
+    /** Ahead of now for a change that has not landed yet. */
+    effective_at: string;
+    /** As recorded, which is not always as asked: a first plan starts at once. */
+    effective: ApplyMode;
+    /** Widened for history: a row written under an older engine may name a mode
+     * the API no longer takes. */
+    reconciliation: RecordedReconciliation;
+    /** What periods are measured from. A plan change inherits it, so a
+     * customer's renewal day never moves under them — `reconciliation: "reset"`
+     * is the one thing that moves it. */
+    anchor_at: string;
+    /** Set when a newer instruction replaced this one before it took effect. */
+    superseded_at: string | null;
+    created_at: string;
+};
+/** Assigning and changing are one operation: the history is append-only. */
+type AssignPlanParams = {
+    plan_id: string;
+    /** Defaults to `next_cycle` on a change, and is forced to `immediate` on a
+     * customer's first plan: there is no period to wait out. */
+    effective?: ApplyMode;
+    /** `immediate` only; the engine refuses it beside `next_cycle`. */
+    reconciliation?: Reconciliation;
+    /** The customer's first assignment only, and the one chance to stagger
+     * their billing day. Defaults to the instant it lands. Refused beside
+     * `reconciliation: "reset"`, which anchors at the change instant itself. */
+    cycle_anchor?: string;
+};
+/**
+ * The plan-change helpers name the plan `plan` rather than `plan_id`: they sit
+ * a layer above the wire, where the engine's own `assign` still mirrors it
+ * field for field.
+ */
+type PlanChangeParams = {
+    /** The plan to move to, by its Meterbase id. */
+    plan: string;
+    /** Defaults to `next_cycle`. */
+    effective?: ApplyMode;
+    /** `immediate` only. Defaults to `none`. */
+    reconciliation?: Reconciliation;
+};
+/** `effective` is fixed to `immediate`; what is left to choose is the fold. */
+type PlanChangeNowParams = Omit<PlanChangeParams, "effective">;
+/** Neither `effective` nor `reconciliation` is open: the call names both. */
+type PlanMoveParams = Pick<PlanChangeParams, "plan">;
+/** `plan` is not accepted on a grant: the engine mints those itself when a
+ * plan is assigned. */
+type AllowanceSource = "purchased" | "bonus" | "manual";
+type Allowance = {
+    id: string;
+    workspace_id: string;
+    customer_id: string;
+    meter_id: string;
+    amount: number | null;
+    no_cap: boolean;
+    consumed: number;
+    /** `null` under no_cap. */
+    remaining: number | null;
+    source: AllowanceSource | "plan";
+    metadata: Record<string, unknown>;
+    effective_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+    exhausted_at: string | null;
+    created_at: string;
+    /** Null unless `source` is `plan`. Together they answer where the grant
+     * came from and why it went away. */
+    plan_allowance_version_id: string | null;
+    assignment_id: string | null;
+    cancelled_at: string | null;
+};
+/** Give exactly one of `amount` or `no_cap`. Unlike a plan allowance, a grant
+ * of 0 is refused: a grant that gives nothing is a no-op, not a state. */
+type AllowanceGrantParams = {
+    meter_id: string;
+    /** At least 1. */
+    amount?: number;
+    no_cap?: boolean;
+    /** Required: the engine will not guess why capacity was handed out. */
+    source: AllowanceSource;
+    metadata?: Record<string, unknown>;
+    /** Defaults to now. Dated ahead, the grant is inert until then. */
+    effective_at?: string;
+    expires_at?: string;
+};
+type AllowanceListParams = {
+    meter_id?: string;
+    /** Revoked, expired and exhausted grants as well as open ones. */
+    include_closed?: boolean;
+};
+type WhoAmI = {
+    workspace: string;
+    caller: string;
+    kind: "api_key" | "service";
+};
+
+/**
+ * Capacity handed to one customer on top of their plan. A grant with
+ * `source: "plan"` is the engine's own, minted when a plan is assigned, and
+ * cannot be created here.
+ */
+declare class CustomerAllowances {
+    #private;
+    constructor(client: Client);
+    grant(customerId: string, params: AllowanceGrantParams, options?: RequestOptions): Promise<Allowance>;
+    /** Open grants only, unless `include_closed`. */
+    list(customerId: string, params?: AllowanceListParams, options?: RequestOptions): Promise<List<Allowance>>;
+    retrieve(customerId: string, allowanceId: string, options?: RequestOptions): Promise<Allowance>;
+    /** Withdraws what is left without erasing what was consumed. Idempotent. */
+    revoke(customerId: string, allowanceId: string, options?: RequestOptions): Promise<Allowance>;
+}
+
+/**
+ * Which plan a customer holds. The history is append-only: there is no patch
+ * and no delete, and moving a customer to a different plan is the same call as
+ * their first.
+ *
+ * `assign` is that call, mirroring the wire. The rest name the four moves a
+ * caller actually makes — later, now, now-and-start-over, and never mind — so
+ * that picking one does not mean knowing what `effective` and `reconciliation`
+ * do to a half-used period.
+ */
+declare class CustomerPlan {
+    #private;
+    constructor(client: Client);
+    /**
+     * Put a customer on a plan. This is the wire call, and the only one that
+     * takes `cycle_anchor` — a first assignment's one chance to put their
+     * periods on a date they already have.
+     *
+     * Returns the instruction as recorded, which is not always as asked: a first
+     * plan is recorded `immediate` whatever `effective` said.
+     */
+    assign(customerId: string, params: AssignPlanParams, options?: RequestOptions): Promise<Assignment>;
+    /**
+     * Move a customer to a different plan, with both knobs in the open.
+     * `effective` defaults to `next_cycle`; `reconciliation` applies only to an
+     * `immediate` change and defaults to `none`.
+     *
+     * Reach for `changeAtNextCycle`, `changeNow` or `restart` when one of them
+     * says what you mean — this is the form to fall back to when the two are
+     * chosen at runtime.
+     */
+    change(customerId: string, params: PlanChangeParams, options?: RequestOptions): Promise<Assignment>;
+    /**
+     * Schedule the move for the end of the period they are in: they keep the
+     * plan they are paying for until it runs out, and the new one starts at
+     * their next boundary. Nothing is pro-rated, because nothing is split.
+     *
+     * Two plans on different cycles share no boundary, and this answers
+     * `CycleChangeRequiresResetError` — use `restart` for that move.
+     */
+    changeAtNextCycle(customerId: string, params: PlanMoveParams, options?: RequestOptions): Promise<Assignment>;
+    /**
+     * Move them now, inside the period already running. Their renewal day does
+     * not move; what changes is this period's cap, and `reconciliation` says
+     * how:
+     *
+     * - `none` (the default) — the new plan's amount governs the whole period.
+     *   Usage already spent still counts, so a downgrade can deny until the
+     *   period ends.
+     * - `prorate` — each plan's amount weighted by the fraction of the period it
+     *   was held for. Refused between plans on different cycles, which share no
+     *   period to weight.
+     *
+     * To have the period itself start over instead, use `restart`.
+     */
+    changeNow(customerId: string, params: PlanChangeNowParams, options?: RequestOptions): Promise<Assignment>;
+    /**
+     * Move them now and start a fresh period today: the period they were in
+     * closes where the change lands, keeping the usage it had, and the new
+     * plan's full amount opens immediately.
+     *
+     * This moves the customer's anchor, so their renewal day becomes today. It
+     * is the move for a customer starting over — a new contract, a re-signup —
+     * and the only one that can take a customer between plans whose cycles
+     * differ.
+     */
+    restart(customerId: string, params: PlanMoveParams, options?: RequestOptions): Promise<Assignment>;
+    /**
+     * Call off a change that has not landed yet, leaving the customer on the
+     * plan they hold. Naming the plan already held is what supersedes a pending
+     * instruction, so this reads the plan in force and names it back.
+     *
+     * Returns the assignment still in force, or `null` for a customer holding no
+     * plan — who can have nothing pending, since a first assignment always lands
+     * at once.
+     */
+    cancelScheduledChange(customerId: string, options?: RequestOptions): Promise<Assignment | null>;
+    /**
+     * The plan in force now, which is not always the newest instruction: a
+     * change dated ahead does not govern yet.
+     *
+     * `null` when the customer holds no plan. That is a default deny rather than
+     * a failure — they are entitled to nothing — so it is an answer here and not
+     * a thrown `NotFoundError`. A customer who does not exist at all still
+     * throws one.
+     */
+    retrieve(customerId: string, options?: RequestOptions): Promise<Assignment | null>;
+    /**
+     * The change waiting to land, or `null` when none is. At most one is ever
+     * live: a newer instruction supersedes the one before it.
+     *
+     * Read against the assignment in force rather than against the local clock,
+     * so a change landing seconds from now is not reported as already governing.
+     */
+    pending(customerId: string, options?: RequestOptions): Promise<Assignment | null>;
+    /** Every instruction, superseded ones included: it is the whole trail. */
+    history(customerId: string, options?: RequestOptions): Promise<List<Assignment>>;
+}
+
+declare class Customers {
+    #private;
+    /** The plan they hold, and the trail of instructions that got them there. */
+    readonly plan: CustomerPlan;
+    /** Grants, which sit on top of whatever the plan gives. */
+    readonly allowances: CustomerAllowances;
+    constructor(client: Client);
+    create(params: CustomerCreateParams, options?: RequestOptions): Promise<Customer>;
+    /** Lean: a listing does not embed the plan. Read one customer for that. */
+    list(params?: CustomerListParams, options?: RequestOptions): Promise<List<Customer>>;
+    /**
+     * One customer, with the plan they hold. `plan` is the one in force now and
+     * `pending_plan` the change waiting to land, each `null` when there is
+     * none — so knowing what a customer is on costs no second request.
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<CustomerWithPlan>;
+    /**
+     * Resolves the tenant's own identifier, or null, embedding the plan the way
+     * `retrieve` does. The engine answers this as a filtered list, so a miss is
+     * an empty collection rather than a 404.
+     */
+    retrieveByExternalId(externalId: string, options?: RequestOptions): Promise<CustomerWithPlan | null>;
+    update(id: string, params: CustomerUpdateParams, options?: RequestOptions): Promise<Customer>;
+    /** Soft delete: usage and assignments keep referencing the customer. */
+    delete(id: string, options?: RequestOptions): Promise<Customer>;
+}
+
+declare class Meters {
+    #private;
+    constructor(client: Client);
+    create(params: MeterCreateParams, options?: RequestOptions): Promise<Meter>;
+    list(params?: MeterListParams, options?: RequestOptions): Promise<List<Meter>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Meter>;
+    update(id: string, params: MeterUpdateParams, options?: RequestOptions): Promise<Meter>;
+    /** Soft delete: plans and usage keep referencing the meter. Idempotent. */
+    archive(id: string, options?: RequestOptions): Promise<Meter>;
+}
+
+/**
+ * A plan's entitlement, versioned. There is no update and no delete: an edit
+ * appends the next version, so which amount applied when stays derivable.
+ */
+declare class PlanAllowances {
+    #private;
+    constructor(client: Client);
+    set(planId: string, params: PlanAllowanceSetParams, options?: RequestOptions): Promise<PlanAllowance>;
+    /** Every version of every meter, newest first — history, not just current. */
+    list(planId: string, params?: PlanAllowanceListParams, options?: RequestOptions): Promise<List<PlanAllowance>>;
+}
+declare class Plans {
+    #private;
+    readonly allowances: PlanAllowances;
+    constructor(client: Client);
+    /** A new plan grants nothing; attach entitlement with `allowances.set`. */
+    create(params: PlanCreateParams, options?: RequestOptions): Promise<Plan>;
+    list(params?: PlanListParams, options?: RequestOptions): Promise<List<Plan>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Plan>;
+    update(id: string, params: PlanUpdateParams, options?: RequestOptions): Promise<Plan>;
+    /**
+     * Stops new assignments without withdrawing capacity from anyone already on
+     * the plan, which is why an archived plan still resolves by id. Idempotent.
+     */
+    archive(id: string, options?: RequestOptions): Promise<Plan>;
+}
+
+declare class MeterbaseError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class APIError extends MeterbaseError {
+    readonly status: number;
+    readonly code: string;
+    /** From `X-Request-Id`, when the engine sends one. */
+    readonly requestId: string | undefined;
+    readonly body: unknown;
+    constructor(args: {
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string | undefined;
+        body?: unknown;
+    });
+}
+declare class AuthenticationError extends APIError {
+}
+declare class PermissionDeniedError extends APIError {
+}
+declare class NotFoundError extends APIError {
+}
+declare class ConflictError extends APIError {
+}
+/**
+ * `409 idempotency_conflict`: the key is in use for a different meter or
+ * quantity. A caller told their key is taken asks what it recorded next, so
+ * the engine names the original and this carries it.
+ *
+ * A `ConflictError` still, so `catch (e) { if (e instanceof ConflictError) }`
+ * keeps working.
+ */
+declare class IdempotencyConflictError extends ConflictError {
+    /** The event that key already recorded. Undefined only if the engine sent a
+     * body this could not be read out of. */
+    readonly existingEventId: string | undefined;
+    constructor(args: ConstructorParameters<typeof APIError>[0]);
+}
+declare class InvalidRequestError extends APIError {
+}
+/**
+ * `422 cycle_change_requires_reset`: the two plans measure different cycles,
+ * so a `next_cycle` change has no shared boundary to wait for and a `prorate`
+ * no shared period to weight. The move is `customers.plan.restart`, which
+ * closes the current period and opens a fresh one on the new cycle — or
+ * `changeNow` with the default `reconciliation: "none"` to keep the period
+ * that is running. The engine's `message` says as much.
+ *
+ * An `InvalidRequestError` still, so an existing `catch` keeps working.
+ */
+declare class CycleChangeRequiresResetError extends InvalidRequestError {
+}
+declare class RateLimitError extends APIError {
+    /** Seconds to wait, from `Retry-After`, when the engine sends one. */
+    readonly retryAfter: number | undefined;
+    constructor(args: ConstructorParameters<typeof APIError>[0] & {
+        retryAfter?: number | undefined;
+    });
+}
+declare class ServerError extends APIError {
+}
+declare class ConnectionError extends MeterbaseError {
+}
+declare class TimeoutError extends ConnectionError {
+}
+declare function errorFromResponse(args: {
+    status: number;
+    code: string;
+    message: string;
+    requestId?: string | undefined;
+    retryAfter?: number | undefined;
+    body?: unknown;
+}): APIError;
+
+declare class Meterbase {
+    #private;
+    readonly customers: Customers;
+    readonly meters: Meters;
+    readonly plans: Plans;
+    constructor(options: MeterbaseOptions);
+    /**
+     * Asks whether a customer may consume `quantity` of a meter, named by the
+     * tenant's own external id and the meter's key. Absence of entitlement is
+     * not permission: a customer with no plan and no grant is denied.
+     *
+     * This is the gate, and the only call that ever refuses. Run it before the
+     * work; record the work with `track` afterwards.
+     */
+    check(params: CheckParams, options?: RequestOptions): Promise<CheckResult>;
+    /**
+     * Records usage that already happened — the tokens were spent, the image
+     * was generated — so it never refuses on capacity. A quantity beyond the
+     * customer's capacity is recorded, drives `available` to 0, and the next
+     * `check` says no. The answer is a receipt, not a verdict.
+     *
+     * `idempotency_key` is generated when omitted, so retrying this call — the
+     * SDK's own retries included — replays the original rather than counting
+     * the same work twice.
+     */
+    track(params: TrackParams, options?: RequestOptions): Promise<TrackResult>;
+    /** Reports which workspace this key acts for. */
+    whoami(options?: RequestOptions): Promise<WhoAmI>;
+}
+
+export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckResult, ConflictError, ConnectionError, type Customer, CustomerAllowances, type CustomerCreateParams, type CustomerListParams, CustomerPlan, type CustomerUpdateParams, type CustomerWithPlan, Customers, CycleChangeRequiresResetError, type EmbeddedPlan, IdempotencyConflictError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterListParams, type MeterUpdateParams, Meterbase, MeterbaseError, type MeterbaseOptions, Meters, NotFoundError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, PlanAllowances, type PlanChangeNowParams, type PlanChangeParams, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanMoveParams, type PlanUpdateParams, Plans, RateLimitError, type Reconciliation, type RecordedReconciliation, type RequestOptions, ServerError, TimeoutError, type TrackParams, type TrackResult, type UsageEvent, type Validity, type WhoAmI, errorFromResponse };