mbase-sdk 0.0.5 → 0.0.7

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";
@@ -527,6 +591,45 @@ type ReleaseResult = {
     reservation_id: string;
     quantity: number;
 };
+/** What a threshold crossing reports, as `threshold.crossed` and `entitlement.reached` send it. */
+type ThresholdCrossing = {
+    /** The tenant's own customer id and the meter key. */
+    customer_id: string;
+    meter_id: string;
+    /** The plan in force when it crossed; `null` if they held none. */
+    plan: {
+        id: string;
+        key: string;
+        name: string;
+    } | null;
+    /** A whole percent, 1–1000; past 100 is an overage alert. */
+    threshold: number;
+    /** The plan's figures at the crossing; neither includes grants. */
+    used: number;
+    entitlement: number;
+    period: {
+        start: string;
+        end: string;
+    };
+    usage_event_id: string | null;
+};
+/** Sent for every mark a customer crosses. */
+type ThresholdCrossedEvent = {
+    /** The same on every attempt and every endpoint: dedupe on it. */
+    id: string;
+    type: "threshold.crossed";
+    timestamp: string;
+    data: ThresholdCrossing;
+};
+/** Sent for the 100% crossing too, under its own id. */
+type EntitlementReachedEvent = {
+    id: string;
+    type: "entitlement.reached";
+    timestamp: string;
+    data: ThresholdCrossing;
+};
+/** New types can be added; ignore any you do not handle. */
+type WebhookEvent = ThresholdCrossedEvent | EntitlementReachedEvent;
 
 /**
  * Capacity handed to one customer on top of their plan. A grant with
@@ -665,6 +768,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>;
@@ -677,6 +788,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>;
 }
@@ -800,6 +913,29 @@ declare function errorFromResponse(args: {
     retryAfter?: number | undefined;
     body?: unknown;
 }): APIError;
+/** A webhook that is not one Meterbase signed recently: answer it with a 400. */
+declare class WebhookVerificationError extends MeterbaseError {
+}
+
+/** A `Headers` object, or Node's lowercase header record. */
+type WebhookHeaders = {
+    get(name: string): string | null;
+} | Record<string, string | string[] | undefined>;
+type VerifyWebhookParams = {
+    /** The body exactly as received. Re-serialized JSON will not verify. */
+    payload: string | Uint8Array;
+    headers: WebhookHeaders;
+    /** The endpoint's `whsec_…` secret; pass both while rotating. */
+    secret: string | readonly string[];
+    /** How far `webhook-timestamp` may be from now. Five minutes by default. */
+    toleranceSeconds?: number;
+};
+/**
+ * Checks a delivery's signature and timestamp the Standard Webhooks way, then
+ * returns the event. Throws `WebhookVerificationError` when it is not one
+ * Meterbase signed recently.
+ */
+declare function verifyWebhook(params: VerifyWebhookParams): Promise<WebhookEvent>;
 
 /**
  * A granted hold, with the two calls that close it. `commit` is `track` under
@@ -909,4 +1045,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, 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 };
+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 EntitlementReachedEvent, 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, type ThresholdCrossedEvent, type ThresholdCrossing, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageDaysParams, type UsageEvent, type UsagePeriod, type UsagePeriodParams, type Validity, type VerifyWebhookParams, type WebhookEvent, type WebhookHeaders, WebhookVerificationError, type WhoAmI, errorFromResponse, verifyWebhook };

package/dist/index.js

@@ -95,6 +95,8 @@ function serverTime(body) {
   const parsed = new Date(at);
   return Number.isNaN(parsed.getTime()) ? void 0 : parsed;
 }
+var WebhookVerificationError = class extends MeterbaseError {
+};
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.meterbase.tech";
@@ -135,7 +137,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+."
       );
     }
   }
@@ -506,6 +508,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,
@@ -561,6 +593,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({
@@ -647,6 +688,84 @@ var Plans = class {
   }
 };
 
+// src/webhooks.ts
+var SECRET_PREFIX = "whsec_";
+var DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+async function verifyWebhook(params) {
+  const id = header(params.headers, "webhook-id");
+  const timestamp = header(params.headers, "webhook-timestamp");
+  const signatures = header(params.headers, "webhook-signature");
+  if (!id || !timestamp || !signatures) {
+    throw new WebhookVerificationError(
+      "Missing a webhook-id, webhook-timestamp or webhook-signature header."
+    );
+  }
+  const sentAt = Number(timestamp);
+  const tolerance = params.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1e3 - sentAt) > tolerance) {
+    throw new WebhookVerificationError(
+      "The webhook-timestamp is too far from now; this may be a replay."
+    );
+  }
+  const body = typeof params.payload === "string" ? new TextEncoder().encode(params.payload) : params.payload;
+  const signed = concat(new TextEncoder().encode(`${id}.${timestamp}.`), body);
+  const candidates = signatures.split(" ").filter((entry) => entry.startsWith("v1,")).map((entry) => fromBase64(entry.slice(3)));
+  const subtle = webCrypto();
+  const secrets = typeof params.secret === "string" ? [params.secret] : params.secret;
+  for (const secret of secrets) {
+    const raw = secret.startsWith(SECRET_PREFIX) ? fromBase64(secret.slice(SECRET_PREFIX.length)) : void 0;
+    if (!raw) {
+      throw new WebhookVerificationError(
+        "The secret should be whsec_ and base64: copy it from the endpoint's settings."
+      );
+    }
+    const key = await subtle.importKey(
+      "raw",
+      raw,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"]
+    );
+    for (const candidate of candidates) {
+      if (candidate && await subtle.verify("HMAC", key, candidate, signed)) {
+        return JSON.parse(new TextDecoder().decode(body));
+      }
+    }
+  }
+  throw new WebhookVerificationError(
+    "No signature matches: the body changed, or this is the wrong secret."
+  );
+}
+function header(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const value = headers[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+function webCrypto() {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new MeterbaseError(
+      "No Web Crypto to verify a webhook with: run on Node 20+, Deno, Bun or a Worker."
+    );
+  }
+  return subtle;
+}
+function fromBase64(text) {
+  try {
+    return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+  } catch {
+    return void 0;
+  }
+}
+function concat(head, tail) {
+  const out = new Uint8Array(head.length + tail.length);
+  out.set(head);
+  out.set(tail, head.length);
+  return out;
+}
+
 // src/index.ts
 var Meterbase = class {
   customers;
@@ -867,6 +986,6 @@ function idempotencyKey(atMs) {
   ].join("-");
 }
 
-export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, InvalidIdempotencyKeyError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PermissionDeniedError, RateLimitError, ReservationMismatchError, ServerError, TimeoutError, TooLateError, errorFromResponse };
+export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, InvalidIdempotencyKeyError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PermissionDeniedError, RateLimitError, ReservationMismatchError, ServerError, TimeoutError, TooLateError, WebhookVerificationError, errorFromResponse, verifyWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map