mbase-sdk 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -432,6 +432,70 @@ type PlanChangeParams = {
 type PlanChangeNowParams = Omit<PlanChangeParams, "effective">;
 /** Neither `effective` nor `reconciliation` is open: the call names both. */
 type PlanMoveParams = Pick<PlanChangeParams, "plan">;
+/** `awaiting`: the plan meters this, but its only versions land later. */
+type EntitlementState = "granted" | "awaiting";
+/** `used` counts toward `amount`; `total` adds what grants paid for. */
+type MeterEntitlement = {
+    meter_id: string;
+    state: EntitlementState;
+    version: PlanAllowance | null;
+    amount: number | null;
+    no_cap: boolean;
+    used: number;
+    total: number;
+    remaining: number | null;
+    reserved: number;
+    available: number | null;
+    incoming: {
+        version: PlanAllowance;
+        lands_at: string;
+    } | null;
+};
+/** The current period only, and only the meters the plan meters. */
+type CustomerEntitlement = {
+    customer_id: string;
+    plan_id: string;
+    cycle: PlanCycle;
+    since: string;
+    period: {
+        start: string;
+        end: string;
+    };
+    meters: MeterEntitlement[];
+};
+type UsagePeriod = "current" | "last";
+/** 1–90 UTC days, ending today. */
+type UsageDaysParams = {
+    days: number;
+    period?: never;
+};
+type UsagePeriodParams = {
+    period: UsagePeriod;
+    days?: never;
+};
+type CustomerUsageParams = UsageDaysParams | UsagePeriodParams;
+type DayUsage = {
+    /** A UTC day, `YYYY-MM-DD`. */
+    date: string;
+    quantity: number;
+};
+/** Every day of the range that has begun, zeros included. */
+type MeterUsage = {
+    meter_id: string;
+    total: number;
+    days: DayUsage[];
+};
+/** `[from, to)`. Only the meters with usage in the range. */
+type CustomerUsage = {
+    customer_id: string;
+    from: string;
+    to: string;
+    meters: MeterUsage[];
+};
+type MeterUsageHistory = MeterUsage & {
+    from: string;
+    to: string;
+};
 /** `plan` is not accepted on a grant: the engine mints those itself when a
  * plan is assigned. */
 type AllowanceSource = "purchased" | "bonus" | "manual";
@@ -482,6 +546,51 @@ 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
@@ -620,6 +729,14 @@ declare class Customers$1 {
      * an empty collection rather than a 404.
      */
     retrieveByExternalId(externalId: string, options?: RequestOptions): Promise<CustomerWithPlan | null>;
+    /** `null` for a customer holding no plan, as `plan.retrieve` answers. */
+    entitlement(id: string, options?: RequestOptions): Promise<CustomerEntitlement | null>;
+    /**
+     * Usage per UTC day. A period the customer never had, holding no plan now
+     * or none before this period, is `null`.
+     */
+    usage(id: string, params: UsageDaysParams, options?: RequestOptions): Promise<CustomerUsage>;
+    usage(id: string, params: UsagePeriodParams, options?: RequestOptions): Promise<CustomerUsage | 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>;
@@ -632,6 +749,8 @@ declare class Meters$1 {
     list(params?: MeterListParams, options?: RequestOptions): Promise<List<Meter>>;
     retrieve(id: string, options?: RequestOptions): Promise<Meter>;
     update(id: string, params: MeterUpdateParams, options?: RequestOptions): Promise<Meter>;
+    /** Every customer's usage of the meter per UTC day. */
+    usage(id: string, params: UsageDaysParams, options?: RequestOptions): Promise<MeterUsageHistory>;
     /** Soft delete: plans and usage keep referencing the meter. Idempotent. */
     archive(id: string, options?: RequestOptions): Promise<Meter>;
 }
@@ -714,6 +833,14 @@ declare class TooLateError extends InvalidRequestError {
     readonly serverTime: Date | undefined;
     constructor(args: ConstructorParameters<typeof APIError>[0]);
 }
+/**
+ * `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,
  * so a `next_cycle` change has no shared boundary to wait for and a `prorate`
@@ -748,6 +875,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;
@@ -781,6 +945,28 @@ declare class Meterbase {
      * 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>;
 }
@@ -797,4 +983,4 @@ 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 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 };
+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 CustomerEntitlement, type CustomerListParams, type CustomerPlan, type CustomerUpdateParams, type CustomerUsage, type CustomerUsageParams, type CustomerWithPlan, type Customers, CycleChangeRequiresResetError, type DayUsage, type EmbeddedPlan, type EntitlementState, type Hold, InvalidIdempotencyKeyError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterEntitlement, type MeterListParams, type MeterUpdateParams, type MeterUsage, type MeterUsageHistory, 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 UsageDaysParams, type UsageEvent, type UsagePeriod, type UsagePeriodParams, type Validity, type WhoAmI, errorFromResponse };

package/dist/index.js

@@ -39,6 +39,8 @@ var TooLateError = class extends InvalidRequestError {
     this.serverTime = serverTime(args.body);
   }
 };
+var ReservationMismatchError = class extends InvalidRequestError {
+};
 var CycleChangeRequiresResetError = class extends InvalidRequestError {
 };
 var RateLimitError = class extends APIError {
@@ -71,6 +73,8 @@ function errorFromResponse(args) {
           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:
@@ -131,7 +135,7 @@ var Client = class {
     this.#fetch = options.fetch ?? globalThis.fetch;
     if (typeof this.#fetch !== "function") {
       throw new MeterbaseError(
-        "No fetch implementation: pass one as `fetch`, or run on Node 18+."
+        "No fetch implementation: pass one as `fetch`, or run on Node 20+."
       );
     }
   }
@@ -502,6 +506,36 @@ var Customers = class {
     });
     return data[0] ?? null;
   }
+  /** `null` for a customer holding no plan, as `plan.retrieve` answers. */
+  async entitlement(id, options) {
+    try {
+      return await this.#client.request({
+        ...options,
+        method: "GET",
+        path: `/v1/customers/${encodeURIComponent(id)}/entitlement`
+      });
+    } catch (error) {
+      if (error instanceof NotFoundError && error.code === "no_plan_assigned") {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async usage(id, params, options) {
+    try {
+      return await this.#client.request({
+        ...options,
+        method: "GET",
+        path: `/v1/customers/${encodeURIComponent(id)}/usage`,
+        query: { days: params.days, period: params.period }
+      });
+    } catch (error) {
+      if (error instanceof NotFoundError && (error.code === "no_plan_assigned" || error.code === "no_previous_period")) {
+        return null;
+      }
+      throw error;
+    }
+  }
   update(id, params, options) {
     return this.#client.request({
       ...options,
@@ -557,6 +591,15 @@ var Meters = class {
       body: params
     });
   }
+  /** Every customer's usage of the meter per UTC day. */
+  usage(id, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/meters/${encodeURIComponent(id)}/usage`,
+      query: { days: params.days }
+    });
+  }
   /** Soft delete: plans and usage keep referencing the meter. Idempotent. */
   archive(id, options) {
     return this.#client.request({
@@ -691,18 +734,83 @@ var Meterbase = class {
   // `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) {
-    const send = (key2) => this.#client.request({
+    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 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
+      path: "/v1/usage/release",
+      body: params
     });
-    if (params.idempotency_key !== void 0) {
-      return send(params.idempotency_key);
-    }
+  }
+  /** Reports which workspace this key acts for. */
+  whoami(options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      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 {
@@ -713,23 +821,59 @@ var Meterbase = class {
       }
       const elapsed = Date.now() - startedAt;
       const serverAtStart = error.serverTime.getTime() - elapsed;
-      if (Math.abs(serverAtStart - mintedAtMs(key)) <= IDEMPOTENCY_WINDOW_MS) {
-        throw error;
-      }
+      if (Math.abs(serverAtStart - mintedAtMs(key)) <= window) throw error;
       this.#client.observeServerTime(error.serverTime);
       return await send(idempotencyKey(this.#client.now()));
     }
   }
-  /** Reports which workspace this key acts for. */
-  whoami(options) {
-    return this.#client.request({
-      ...options,
-      method: "GET",
-      path: "/v1/whoami"
-    });
+  /** 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;
+        }
+      }
+    };
   }
 };
 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);
 }
@@ -762,6 +906,6 @@ function idempotencyKey(atMs) {
   ].join("-");
 }
 
-export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, InvalidIdempotencyKeyError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, TimeoutError, TooLateError, 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