mbase-sdk 0.0.2 → 0.0.5

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -27,16 +27,19 @@ var NotFoundError = class extends APIError {
 };
 var ConflictError = class extends APIError {
 };
-var IdempotencyConflictError = class extends ConflictError {
-  /** The event that key already recorded. Undefined only if the engine sent a
-   * body this could not be read out of. */
-  existingEventId;
+var InvalidRequestError = class extends APIError {
+};
+var InvalidIdempotencyKeyError = class extends InvalidRequestError {
+};
+var TooLateError = class extends InvalidRequestError {
+  /** The engine's clock when it refused. */
+  serverTime;
   constructor(args) {
     super(args);
-    this.existingEventId = existingEventId(args.body);
+    this.serverTime = serverTime(args.body);
   }
 };
-var InvalidRequestError = class extends APIError {
+var ReservationMismatchError = class extends InvalidRequestError {
 };
 var CycleChangeRequiresResetError = class extends InvalidRequestError {
 };
@@ -63,21 +66,34 @@ function errorFromResponse(args) {
     case 404:
       return new NotFoundError(args);
     case 409:
-      return args.code === "idempotency_conflict" ? new IdempotencyConflictError(args) : new ConflictError(args);
+      return new ConflictError(args);
     case 422:
-      return args.code === "cycle_change_requires_reset" ? new CycleChangeRequiresResetError(args) : new InvalidRequestError(args);
+      switch (args.code) {
+        case "cycle_change_requires_reset":
+          return new CycleChangeRequiresResetError(args);
+        case "invalid_idempotency_key":
+          return new InvalidIdempotencyKeyError(args);
+        case "reservation_mismatch":
+          return new ReservationMismatchError(args);
+        case "too_late":
+          return new TooLateError(args);
+        default:
+          return new InvalidRequestError(args);
+      }
     case 429:
       return new RateLimitError(args);
     default:
       return args.status >= 500 ? new ServerError(args) : new APIError(args);
   }
 }
-function existingEventId(body) {
+function serverTime(body) {
   if (typeof body !== "object" || body === null) return void 0;
   const error = body.error;
   if (typeof error !== "object" || error === null) return void 0;
-  const id = error.existing_event_id;
-  return typeof id === "string" ? id : void 0;
+  const at = error.server_time;
+  if (typeof at !== "string") return void 0;
+  const parsed = new Date(at);
+  return Number.isNaN(parsed.getTime()) ? void 0 : parsed;
 }
 
 // src/client.ts
@@ -91,6 +107,21 @@ var Client = class {
   #timeout;
   #maxRetries;
   #fetch;
+  /**
+   * How far the engine's clock is ahead of this machine's, in milliseconds.
+   * Idempotency keys are minted here and the engine refuses one dated more
+   * than an hour from its own clock, so without this a device with a wrong
+   * clock would fail every call forever.
+   */
+  #clockOffset = 0;
+  /** The engine's clock, as well as this client knows it. */
+  now() {
+    return Date.now() + this.#clockOffset;
+  }
+  /** Off by up to one round trip, which a window in hours does not notice. */
+  observeServerTime(at) {
+    this.#clockOffset = at.getTime() - Date.now();
+  }
   constructor(options) {
     if (!options.apiKey) {
       throw new MeterbaseError(
@@ -635,6 +666,12 @@ var Meterbase = class {
    *
    * 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, options) {
     return this.#client.request({
@@ -650,24 +687,70 @@ var Meterbase = class {
    * 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.
    */
   // `async` so that generating the key cannot throw synchronously out of a
   // method that otherwise only ever rejects: one call, one way to fail.
   async track(params, options) {
+    return this.#keyed(
+      IDEMPOTENCY_WINDOW_MS,
+      params.idempotency_key,
+      (key) => this.#client.request({
+        ...options,
+        method: "POST",
+        path: "/v1/usage/track",
+        // Fixed before the retry loop is entered: every attempt of this call
+        // carries the same key, which is what makes replaying it safe.
+        body: { ...params, idempotency_key: key },
+        idempotent: true
+      })
+    );
+  }
+  /**
+   * 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.
+   */
+  async reserve(params, options) {
+    const response = await this.#keyed(
+      RESERVE_WINDOW_MS,
+      params.reservation_id,
+      (id) => this.#client.request({
+        ...options,
+        method: "POST",
+        path: "/v1/usage/reserve",
+        body: { ...params, reservation_id: id },
+        // A retry under the same id finds the hold it already made rather
+        // than making a second one.
+        idempotent: true
+      })
+    );
+    return this.#hold(params, response);
+  }
+  /**
+   * 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, options) {
     return this.#client.request({
       ...options,
       method: "POST",
-      path: "/v1/usage/track",
-      // Fixed here, once, before the retry loop is entered: every attempt of
-      // this call carries the same key, which is what makes replaying it safe.
-      body: {
-        ...params,
-        idempotency_key: params.idempotency_key ?? idempotencyKey()
-      },
-      idempotent: true
+      path: "/v1/usage/release",
+      body: params
     });
   }
   /** Reports which workspace this key acts for. */
@@ -678,21 +761,112 @@ var Meterbase = class {
       path: "/v1/whoami"
     });
   }
+  /**
+   * Sends a call that carries a caller-minted UUIDv7, minting one when the
+   * caller supplied none and re-minting once if this machine's clock put it
+   * outside the engine's window.
+   *
+   * A key the caller supplied is never re-minted: this cannot know whether it
+   * names work already recorded, and replacing it could count that work
+   * twice.
+   */
+  async #keyed(window, supplied, send) {
+    if (supplied !== void 0) return send(supplied);
+    const key = idempotencyKey(this.#client.now());
+    const startedAt = Date.now();
+    try {
+      return await send(key);
+    } catch (error) {
+      if (!(error instanceof TooLateError) || error.serverTime === void 0) {
+        throw error;
+      }
+      const elapsed = Date.now() - startedAt;
+      const serverAtStart = error.serverTime.getTime() - elapsed;
+      if (Math.abs(serverAtStart - mintedAtMs(key)) <= window) throw error;
+      this.#client.observeServerTime(error.serverTime);
+      return await send(idempotencyKey(this.#client.now()));
+    }
+  }
+  /** Puts `commit` and `release` on a granted hold; a refusal is left as it is. */
+  #hold(params, response) {
+    if (!response.allowed) return response;
+    const id = response.reservation_id;
+    const expiresAt = response.expires_at;
+    if (id === void 0 || expiresAt === void 0) {
+      throw new MeterbaseError(
+        "The engine granted a reservation without an id or an expiry, so there is no hold to commit or release. The capacity it set aside comes back on its own."
+      );
+    }
+    const expiresAtMs = Date.parse(expiresAt);
+    return {
+      ...response,
+      allowed: true,
+      reservation_id: id,
+      quantity: response.quantity ?? params.quantity ?? 1,
+      expires_at: expiresAt,
+      commit: (quantity, commitOptions) => {
+        if (Number.isFinite(expiresAtMs) && this.#client.now() > expiresAtMs && typeof globalThis.console?.warn === "function") {
+          globalThis.console.warn(
+            `Meterbase: committing reservation ${id} after it expired at ${expiresAt}. The event is still recorded, but the capacity was no longer held \u2014 raise expires_in_seconds for this work.`
+          );
+        }
+        return this.track(
+          {
+            customer_id: params.customer_id,
+            meter_id: params.meter_id,
+            quantity,
+            // The hold's own id, so the track commits it rather than
+            // recording a second event beside it.
+            idempotency_key: id
+          },
+          commitOptions
+        );
+      },
+      release: async (releaseOptions) => {
+        try {
+          return await this.release({ reservation_id: id }, releaseOptions);
+        } catch (error) {
+          if (error instanceof NotFoundError) return null;
+          throw error;
+        }
+      }
+    };
+  }
 };
-function idempotencyKey() {
+var IDEMPOTENCY_WINDOW_MS = 60 * 60 * 1e3;
+var RESERVE_WINDOW_MS = 30 * 60 * 1e3;
+function mintedAtMs(key) {
+  return Number.parseInt(key.replace(/-/g, "").slice(0, 12), 16);
+}
+function idempotencyKey(atMs) {
   const webcrypto = globalThis.crypto;
-  if (typeof webcrypto?.randomUUID === "function") {
-    return webcrypto.randomUUID();
-  }
-  if (typeof webcrypto?.getRandomValues === "function") {
-    const bytes = webcrypto.getRandomValues(new Uint8Array(16));
-    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  if (typeof webcrypto?.getRandomValues !== "function") {
+    throw new MeterbaseError(
+      "No crypto to generate an idempotency key with: pass `idempotency_key` yourself (a UUIDv7), or run somewhere `crypto.getRandomValues` exists."
+    );
   }
-  throw new MeterbaseError(
-    "No crypto to generate an idempotency key with: pass `idempotency_key` yourself, or run somewhere `crypto.getRandomValues` exists."
-  );
+  const bytes = webcrypto.getRandomValues(new Uint8Array(16));
+  const ms = Math.max(0, Math.trunc(atMs));
+  const high = Math.floor(ms / 4294967296);
+  const low = ms >>> 0;
+  bytes[0] = high >>> 8 & 255;
+  bytes[1] = high & 255;
+  bytes[2] = low >>> 24 & 255;
+  bytes[3] = low >>> 16 & 255;
+  bytes[4] = low >>> 8 & 255;
+  bytes[5] = low & 255;
+  bytes[6] = bytes[6] & 15 | 112;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20)
+  ].join("-");
 }
 
-export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, IdempotencyConflictError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, TimeoutError, errorFromResponse };
+export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, InvalidIdempotencyKeyError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PermissionDeniedError, RateLimitError, ReservationMismatchError, ServerError, TimeoutError, TooLateError, errorFromResponse };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map