mbase-sdk 0.0.2 → 0.0.4

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
@@ -432,7 +488,7 @@ type WhoAmI = {
  * `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 +509,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 +598,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 +625,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 +640,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,22 +690,30 @@ 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 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`
@@ -697,6 +761,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 +775,26 @@ 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>;
     /** 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, 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 RequestOptions, ServerError, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageEvent, type Validity, type WhoAmI, errorFromResponse };

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
@@ -432,7 +488,7 @@ type WhoAmI = {
  * `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 +509,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 +598,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 +625,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 +640,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,22 +690,30 @@ 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 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`
@@ -697,6 +761,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 +775,26 @@ 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>;
     /** 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, 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 RequestOptions, ServerError, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageEvent, type Validity, type WhoAmI, errorFromResponse };

package/dist/index.js

@@ -27,17 +27,18 @@ 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 CycleChangeRequiresResetError = class extends InvalidRequestError {
 };
 var RateLimitError = class extends APIError {
@@ -63,21 +64,32 @@ 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 "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 +103,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 +662,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,25 +683,42 @@ 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.#client.request({
+    const send = (key2) => 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()
-      },
+      // 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: key2 },
       idempotent: true
     });
+    if (params.idempotency_key !== void 0) {
+      return send(params.idempotency_key);
+    }
+    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)) <= IDEMPOTENCY_WINDOW_MS) {
+        throw error;
+      }
+      this.#client.observeServerTime(error.serverTime);
+      return await send(idempotencyKey(this.#client.now()));
+    }
   }
   /** Reports which workspace this key acts for. */
   whoami(options) {
@@ -679,20 +729,39 @@ var Meterbase = class {
     });
   }
 };
-function idempotencyKey() {
+var IDEMPOTENCY_WINDOW_MS = 60 * 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, ServerError, TimeoutError, TooLateError, errorFromResponse };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map