mbase-sdk 0.0.2 → 0.0.5

package/dist/index.d.cts

@@ -29,6 +29,10 @@ type Request = RequestOptions & {
 };
 declare class Client {
     #private;
+    /** The engine's clock, as well as this client knows it. */
+    now(): number;
+    /** Off by up to one round trip, which a window in hours does not notice. */
+    observeServerTime(at: Date): void;
     constructor(options: MeterbaseOptions);
     request<T>(req: Request): Promise<T>;
 }
@@ -164,9 +168,47 @@ type CheckParams = {
      * asks whether there is any capacity at all. */
     quantity?: number;
 };
+/**
+ * Which gate turned the request away. `entitlement` is named ahead of
+ * `rate_limit` when both refuse: running out of plan is the one the customer
+ * can act on, and being told about the window instead would send them to
+ * support over the wrong thing.
+ *
+ * Open on purpose. The engine's contract says this list will grow, and a
+ * closed union would turn every code the engine adds into a build the caller
+ * has to wait on the SDK for. Branch on the codes you know; anything else is
+ * still a refusal, and still means do not do the work.
+ */
+type CheckReason = "entitlement" | "rate_limit" | (string & {});
+/**
+ * One rate-limit window in force for this customer and meter.
+ *
+ * Windows are fixed and clock-aligned — a cell starts at a multiple of the
+ * window counted from the epoch — which is what lets `used` be a literal count
+ * of what the current cell holds and `resets_at` a clock time. A sliding
+ * window would owe the reader a tooltip for both.
+ */
+type CheckRateLimit = {
+    /** A whole number of seconds from `60` to `2592000`: a minute to 30 days. */
+    window_seconds: number;
+    max: number;
+    used: number;
+    /** `max - used`, floored at 0. */
+    remaining: number;
+    /** `used + quantity > max`: this request does not fit in this window. */
+    exceeded: boolean;
+    /** End of the current cell, when `used` goes back to 0. Waiting for it is
+     * the fix for a window that refused — unless the quantity is larger than
+     * `max`, which never fits however long the caller waits. */
+    resets_at: string;
+};
 type CheckResult = {
+    /** Both gates: the capacity covers the quantity **and** every rate-limit
+     * window admits it. */
     allowed: boolean;
-    /** Unlimited for this meter. `available` is `null`. */
+    /** Unlimited for this meter. `available` is `null`. Rate limits still
+     * apply — a customer who is never refused on capacity is the one a runaway
+     * loop costs most. */
     no_cap: boolean;
     /**
      * The whole capacity: the plan's unused entitlement for the current period,
@@ -178,6 +220,20 @@ type CheckResult = {
      * per-grant detail, read `customers.allowances.list`.
      */
     available: number | null;
+    /** Which gate said no. Absent when allowed, so its presence is the denial
+     * and reading it is never a branch on a truthy string. */
+    reason?: CheckReason;
+    /**
+     * Every window in force, refused or not, which is why the engine reports
+     * them on every call: a caller that only heard about a limit when it was
+     * refused could not slow down before it, only after.
+     *
+     * A limit is protective, not commercial, so it sits beside `available` and
+     * is never folded into it — a customer well inside their plan can still be
+     * limited, and the two are fixed by different people for different reasons.
+     * `[]` when no rule applies, which is the ordinary case.
+     */
+    rate_limits: CheckRateLimit[];
 };
 /**
  * `track` records work that already happened, so it never refuses on capacity
@@ -426,13 +482,58 @@ type WhoAmI = {
     caller: string;
     kind: "api_key" | "service";
 };
+/**
+ * A reserve is a check that means it: the same decision, and then a **hold**
+ * on the capacity until a track commits it, a release gives it back, or it
+ * expires. It is the gate for work that cannot be done twice.
+ */
+type ReserveParams = {
+    customer_id: string;
+    meter_id: string;
+    /** What the hold sets aside, `1 … 100000000000`. Defaults to `1`. */
+    quantity?: number;
+    /**
+     * The hold's id, and the event's id once a track commits it. A UUIDv7, and
+     * the SDK mints one when it is omitted.
+     *
+     * An id is for one reserve and its retries. Once its hold is committed or
+     * released the row is gone, so sending the same id again reserves afresh
+     * rather than finding anything.
+     */
+    reservation_id?: string;
+    /**
+     * How long the hold counts against the pair before it comes back on its
+     * own: `1 … 900`, defaulting to `60`.
+     *
+     * It is a timeout on your own work, and the field callers get wrong. Too
+     * short and the hold evaporates mid-operation, which is worse than no hold
+     * at all because you believe you are protected; too long and a crash wedges
+     * the customer's capacity until it expires.
+     */
+    expires_in_seconds?: number;
+};
+/** What the engine answers a reserve with, before the SDK adds its helpers. */
+type ReserveResponse = CheckResult & {
+    /** Present only when allowed: a refusal holds nothing. */
+    reservation_id?: string;
+    quantity?: number;
+    expires_at?: string;
+};
+type ReleaseParams = {
+    reservation_id: string;
+};
+/** The hold that was given back, and what it had set aside. */
+type ReleaseResult = {
+    reservation_id: string;
+    quantity: number;
+};
 
 /**
  * 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 {
+declare class CustomerAllowances$1 {
     #private;
     constructor(client: Client);
     grant(customerId: string, params: AllowanceGrantParams, options?: RequestOptions): Promise<Allowance>;
@@ -453,7 +554,7 @@ declare class CustomerAllowances {
  * that picking one does not mean knowing what `effective` and `reconciliation`
  * do to a half-used period.
  */
-declare class CustomerPlan {
+declare class CustomerPlan$1 {
     #private;
     constructor(client: Client);
     /**
@@ -542,12 +643,12 @@ declare class CustomerPlan {
     history(customerId: string, options?: RequestOptions): Promise<List<Assignment>>;
 }
 
-declare class Customers {
+declare class Customers$1 {
     #private;
     /** The plan they hold, and the trail of instructions that got them there. */
-    readonly plan: CustomerPlan;
+    readonly plan: CustomerPlan$1;
     /** Grants, which sit on top of whatever the plan gives. */
-    readonly allowances: CustomerAllowances;
+    readonly allowances: CustomerAllowances$1;
     constructor(client: Client);
     create(params: CustomerCreateParams, options?: RequestOptions): Promise<Customer>;
     /** Lean: a listing does not embed the plan. Read one customer for that. */
@@ -569,7 +670,7 @@ declare class Customers {
     delete(id: string, options?: RequestOptions): Promise<Customer>;
 }
 
-declare class Meters {
+declare class Meters$1 {
     #private;
     constructor(client: Client);
     create(params: MeterCreateParams, options?: RequestOptions): Promise<Meter>;
@@ -584,16 +685,16 @@ declare class Meters {
  * 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 {
+declare class PlanAllowances$1 {
     #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 {
+declare class Plans$1 {
     #private;
-    readonly allowances: PlanAllowances;
+    readonly allowances: PlanAllowances$1;
     constructor(client: Client);
     /** A new plan grants nothing; attach entitlement with `allowances.set`. */
     create(params: PlanCreateParams, options?: RequestOptions): Promise<Plan>;
@@ -634,21 +735,37 @@ declare class NotFoundError extends APIError {
 }
 declare class ConflictError extends APIError {
 }
+declare class InvalidRequestError extends APIError {
+}
+/**
+ * `422 invalid_idempotency_key`: the key was not a UUID version 7.
+ * `crypto.randomUUID()` mints a v4, so omit `idempotency_key` and let this
+ * SDK mint the right thing.
+ */
+declare class InvalidIdempotencyKeyError extends InvalidRequestError {
+}
 /**
- * `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.
+ * `422 too_late`: the key's timestamp is more than an hour from the engine's
+ * clock, so a retry can no longer be told from a new event. **Nothing was
+ * recorded** — the check runs before any write.
  *
- * A `ConflictError` still, so `catch (e) { if (e instanceof ConflictError) }`
- * keeps working.
+ * The usual cause is this machine's clock. When this SDK minted the key it
+ * corrects the offset from `serverTime` and retries once, so you only see
+ * this for a key you supplied. If that key is a retry of a call made over an
+ * hour ago, do not resend it under a new one: it may already be recorded.
  */
-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;
+declare class TooLateError extends InvalidRequestError {
+    /** The engine's clock when it refused. */
+    readonly serverTime: Date | undefined;
     constructor(args: ConstructorParameters<typeof APIError>[0]);
 }
-declare class InvalidRequestError extends APIError {
+/**
+ * `422 reservation_mismatch`: the reservation id names a hold made for a
+ * different customer or meter than the call sends. A caller bug, refused
+ * before anything is written — nothing was recorded and the hold still
+ * stands.
+ */
+declare class ReservationMismatchError extends InvalidRequestError {
 }
 /**
  * `422 cycle_change_requires_reset`: the two plans measure different cycles,
@@ -684,6 +801,43 @@ declare function errorFromResponse(args: {
     body?: unknown;
 }): APIError;
 
+/**
+ * A granted hold, with the two calls that close it. `commit` is `track` under
+ * the hold's own id; `release` gives the capacity back.
+ */
+type Hold = ReserveResponse & {
+    allowed: true;
+    reservation_id: string;
+    quantity: number;
+    expires_at: string;
+    /**
+     * Records what the work actually cost and releases the rest. Omit the
+     * quantity to record what was held.
+     *
+     * Warns when it runs after `expires_at`: the hold stopped holding anything
+     * at that instant, so the work was no longer protected. That warning is the
+     * only feedback there is on an `expires_in_seconds` guessed too short.
+     */
+    commit(quantity?: number, options?: RequestOptions): Promise<TrackResult>;
+    /**
+     * Gives the hold back. Nothing is recorded.
+     *
+     * Resolves with `null` rather than throwing when there is nothing left to
+     * release — already committed, already released. This is the one call meant
+     * to run on the failure path, where throwing would mask the error the
+     * caller is already handling, and "nothing left to release" is the outcome
+     * a release wanted anyway. `meterbase.release` throws the 404, as every
+     * other call does.
+     */
+    release(options?: RequestOptions): Promise<ReleaseResult | null>;
+};
+/** A refused reserve holds nothing, so it carries no id and no expiry. */
+type ReserveRefused = ReserveResponse & {
+    allowed: false;
+    reservation_id?: undefined;
+    expires_at?: undefined;
+};
+type ReserveResult = Hold | ReserveRefused;
 declare class Meterbase {
     #private;
     readonly customers: Customers;
@@ -697,6 +851,12 @@ declare class Meterbase {
      *
      * This is the gate, and the only call that ever refuses. Run it before the
      * work; record the work with `track` afterwards.
+     *
+     * Two gates answer it, and `allowed` needs both: the customer's capacity has
+     * to cover the quantity, and every rate-limit window in force has to admit
+     * it. `reason` names the one that said no. `rate_limits` reports each window
+     * whether or not it refused, so a caller can ease off as its headroom closes
+     * instead of discovering the ceiling by hitting it.
      */
     check(params: CheckParams, options?: RequestOptions): Promise<CheckResult>;
     /**
@@ -705,13 +865,48 @@ declare class Meterbase {
      * 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.
+     * `idempotency_key` is a UUIDv7, generated when omitted, so retrying this
+     * call — the SDK's own retries included — replays the original rather than
+     * counting the same work twice. The engine keeps that claim for an hour,
+     * which is how long a retry stays recognisable.
      */
     track(params: TrackParams, options?: RequestOptions): Promise<TrackResult>;
+    /**
+     * Holds capacity for work that cannot be done twice, or refuses. The same
+     * decision `check` makes, and then a hold on the capacity until the work
+     * is committed, released, or expires.
+     *
+     * The rule for choosing: can you afford to do the work twice? `check`. No?
+     * `reserve`. A reserve costs a transaction where a check costs a cached
+     * read, refusals included, so it is not a per-request gate on cheap work.
+     *
+     * Two concurrent reserves for the same customer and meter cannot both be
+     * granted the same capacity; that is the whole point, and it is what
+     * `check` → work → `track` could never promise.
+     */
+    reserve(params: ReserveParams, options?: RequestOptions): Promise<ReserveResult>;
+    /**
+     * Gives a hold back: the work did not happen, so nothing is recorded.
+     *
+     * Throws `NotFoundError` when the id names nothing — committed, released
+     * already, or never made, which are one absence with one meaning. Prefer
+     * `hold.release()`, which treats that as the success it is.
+     */
+    release(params: ReleaseParams, options?: RequestOptions): Promise<ReleaseResult>;
     /** Reports which workspace this key acts for. */
     whoami(options?: RequestOptions): Promise<WhoAmI>;
 }
+/**
+ * The resource namespaces, type-only: none is constructible without the
+ * unexported Client. Instance types rather than `export type { Customers }`,
+ * which the declaration bundler re-emits as a value export — promising a
+ * runtime binding the bundle never has.
+ */
+type CustomerAllowances = InstanceType<typeof CustomerAllowances$1>;
+type CustomerPlan = InstanceType<typeof CustomerPlan$1>;
+type Customers = InstanceType<typeof Customers$1>;
+type Meters = InstanceType<typeof Meters$1>;
+type PlanAllowances = InstanceType<typeof PlanAllowances$1>;
+type Plans = InstanceType<typeof Plans$1>;
 
-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 };
+export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckRateLimit, type CheckReason, type CheckResult, ConflictError, ConnectionError, type Customer, type CustomerAllowances, type CustomerCreateParams, type CustomerListParams, type CustomerPlan, type CustomerUpdateParams, type CustomerWithPlan, type Customers, CycleChangeRequiresResetError, type EmbeddedPlan, type Hold, InvalidIdempotencyKeyError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterListParams, type MeterUpdateParams, Meterbase, MeterbaseError, type MeterbaseOptions, type Meters, NotFoundError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, type PlanAllowances, type PlanChangeNowParams, type PlanChangeParams, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanMoveParams, type PlanUpdateParams, type Plans, RateLimitError, type Reconciliation, type RecordedReconciliation, type ReleaseParams, type ReleaseResult, type RequestOptions, ReservationMismatchError, type ReserveParams, type ReserveRefused, type ReserveResponse, type ReserveResult, ServerError, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageEvent, type Validity, type WhoAmI, errorFromResponse };