mbase-sdk 0.0.2

package/dist/index.cjs

@@ -0,0 +1,714 @@
+'use strict';
+
+// src/errors.ts
+var MeterbaseError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var APIError = class extends MeterbaseError {
+  status;
+  code;
+  /** From `X-Request-Id`, when the engine sends one. */
+  requestId;
+  body;
+  constructor(args) {
+    super(args.message);
+    this.status = args.status;
+    this.code = args.code;
+    this.requestId = args.requestId;
+    this.body = args.body;
+  }
+};
+var AuthenticationError = class extends APIError {
+};
+var PermissionDeniedError = class extends APIError {
+};
+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;
+  constructor(args) {
+    super(args);
+    this.existingEventId = existingEventId(args.body);
+  }
+};
+var InvalidRequestError = class extends APIError {
+};
+var CycleChangeRequiresResetError = class extends InvalidRequestError {
+};
+var RateLimitError = class extends APIError {
+  /** Seconds to wait, from `Retry-After`, when the engine sends one. */
+  retryAfter;
+  constructor(args) {
+    super(args);
+    this.retryAfter = args.retryAfter;
+  }
+};
+var ServerError = class extends APIError {
+};
+var ConnectionError = class extends MeterbaseError {
+};
+var TimeoutError = class extends ConnectionError {
+};
+function errorFromResponse(args) {
+  switch (args.status) {
+    case 401:
+      return new AuthenticationError(args);
+    case 403:
+      return new PermissionDeniedError(args);
+    case 404:
+      return new NotFoundError(args);
+    case 409:
+      return args.code === "idempotency_conflict" ? new IdempotencyConflictError(args) : new ConflictError(args);
+    case 422:
+      return args.code === "cycle_change_requires_reset" ? new CycleChangeRequiresResetError(args) : new InvalidRequestError(args);
+    case 429:
+      return new RateLimitError(args);
+    default:
+      return args.status >= 500 ? new ServerError(args) : new APIError(args);
+  }
+}
+function existingEventId(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;
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.meterbase.tech";
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_MAX_RETRIES = 2;
+var MAX_BACKOFF = 8e3;
+var Client = class {
+  #apiKey;
+  #baseUrl;
+  #timeout;
+  #maxRetries;
+  #fetch;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new MeterbaseError(
+        "An API key is required: new Meterbase({ apiKey: 'mb_sk_live_\u2026' })."
+      );
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    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+."
+      );
+    }
+  }
+  async request(req) {
+    const maxRetries = req.maxRetries ?? this.#maxRetries;
+    const retryable = req.method === "GET" || req.method === "DELETE" || req.idempotent === true;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (attempt > 0) await sleep(backoff(attempt, lastError));
+      try {
+        const response = await this.#send(req);
+        if (response.ok) return await parseBody(response);
+        const error = await errorFrom(response);
+        if (retryable && attempt < maxRetries && shouldRetry(response.status)) {
+          lastError = error;
+          continue;
+        }
+        throw error;
+      } catch (cause) {
+        if (cause instanceof MeterbaseError && !(cause instanceof ConnectionError)) {
+          throw cause;
+        }
+        if (!retryable || attempt >= maxRetries) throw cause;
+        lastError = cause;
+      }
+    }
+    throw lastError;
+  }
+  async #send(req) {
+    const url = new URL(this.#baseUrl + req.path);
+    for (const [key, value] of Object.entries(req.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = {
+      authorization: `Bearer ${this.#apiKey}`,
+      accept: "application/json"
+    };
+    if (req.body !== void 0) headers["content-type"] = "application/json";
+    const timeout = req.timeout ?? this.#timeout;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(req.signal?.reason);
+    req.signal?.addEventListener("abort", onAbort, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeout);
+    try {
+      return await this.#fetch(url, {
+        method: req.method,
+        headers,
+        body: req.body === void 0 ? void 0 : JSON.stringify(req.body),
+        signal: controller.signal
+      });
+    } catch (cause) {
+      if (timedOut) {
+        throw new TimeoutError(`Request timed out after ${timeout}ms.`, {
+          cause
+        });
+      }
+      if (req.signal?.aborted) throw cause;
+      throw new ConnectionError(`Could not reach ${url.origin}.`, { cause });
+    } finally {
+      clearTimeout(timer);
+      req.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+};
+function shouldRetry(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+function backoff(attempt, lastError) {
+  const retryAfter = lastError && typeof lastError === "object" && "retryAfter" in lastError ? lastError.retryAfter : void 0;
+  if (retryAfter !== void 0) return Math.min(retryAfter * 1e3, MAX_BACKOFF);
+  const ceiling = Math.min(500 * 2 ** (attempt - 1), MAX_BACKOFF);
+  return Math.random() * ceiling;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parseBody(response) {
+  if (response.status === 204) return void 0;
+  const text = await response.text();
+  if (text === "") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new MeterbaseError("The engine returned a body that is not JSON.", {
+      cause
+    });
+  }
+}
+async function errorFrom(response) {
+  const body = await response.text();
+  const parsed = parseErrorBody(body);
+  const retryAfterHeader = response.headers.get("retry-after");
+  const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : void 0;
+  return errorFromResponse({
+    status: response.status,
+    code: parsed?.code ?? `http_${response.status}`,
+    message: parsed?.message ?? `The engine responded ${response.status}.`,
+    requestId: response.headers.get("x-request-id") ?? void 0,
+    retryAfter: retryAfter !== void 0 && Number.isFinite(retryAfter) ? retryAfter : void 0,
+    body: body === "" ? void 0 : safeParse(body) ?? body
+  });
+}
+function parseErrorBody(body) {
+  const parsed = safeParse(body);
+  const error = parsed?.error;
+  if (!error?.code || !error.message) return void 0;
+  return { code: error.code, message: error.message };
+}
+function safeParse(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/resources/customer-allowances.ts
+var CustomerAllowances = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  grant(customerId, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: `/v1/customers/${encodeURIComponent(customerId)}/allowances`,
+      body: params
+    });
+  }
+  /** Open grants only, unless `include_closed`. */
+  list(customerId, params = {}, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/customers/${encodeURIComponent(customerId)}/allowances`,
+      query: {
+        meter_id: params.meter_id,
+        include_closed: params.include_closed
+      }
+    });
+  }
+  retrieve(customerId, allowanceId, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/customers/${encodeURIComponent(customerId)}/allowances/${encodeURIComponent(allowanceId)}`
+    });
+  }
+  /** Withdraws what is left without erasing what was consumed. Idempotent. */
+  revoke(customerId, allowanceId, options) {
+    return this.#client.request({
+      ...options,
+      method: "DELETE",
+      path: `/v1/customers/${encodeURIComponent(customerId)}/allowances/${encodeURIComponent(allowanceId)}`
+    });
+  }
+};
+
+// src/resources/customer-plan.ts
+var CustomerPlan = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * Put a customer on a plan. This is the wire call, and the only one that
+   * takes `cycle_anchor` — a first assignment's one chance to put their
+   * periods on a date they already have.
+   *
+   * Returns the instruction as recorded, which is not always as asked: a first
+   * plan is recorded `immediate` whatever `effective` said.
+   */
+  assign(customerId, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: `/v1/customers/${encodeURIComponent(customerId)}/plan`,
+      body: params
+    });
+  }
+  /**
+   * Move a customer to a different plan, with both knobs in the open.
+   * `effective` defaults to `next_cycle`; `reconciliation` applies only to an
+   * `immediate` change and defaults to `none`.
+   *
+   * Reach for `changeAtNextCycle`, `changeNow` or `restart` when one of them
+   * says what you mean — this is the form to fall back to when the two are
+   * chosen at runtime.
+   */
+  change(customerId, params, options) {
+    const { plan, ...rest } = params;
+    return this.assign(customerId, { plan_id: plan, ...rest }, options);
+  }
+  /**
+   * Schedule the move for the end of the period they are in: they keep the
+   * plan they are paying for until it runs out, and the new one starts at
+   * their next boundary. Nothing is pro-rated, because nothing is split.
+   *
+   * Two plans on different cycles share no boundary, and this answers
+   * `CycleChangeRequiresResetError` — use `restart` for that move.
+   */
+  changeAtNextCycle(customerId, params, options) {
+    return this.change(
+      customerId,
+      { plan: params.plan, effective: "next_cycle" },
+      options
+    );
+  }
+  /**
+   * Move them now, inside the period already running. Their renewal day does
+   * not move; what changes is this period's cap, and `reconciliation` says
+   * how:
+   *
+   * - `none` (the default) — the new plan's amount governs the whole period.
+   *   Usage already spent still counts, so a downgrade can deny until the
+   *   period ends.
+   * - `prorate` — each plan's amount weighted by the fraction of the period it
+   *   was held for. Refused between plans on different cycles, which share no
+   *   period to weight.
+   *
+   * To have the period itself start over instead, use `restart`.
+   */
+  changeNow(customerId, params, options) {
+    return this.change(
+      customerId,
+      { ...params, effective: "immediate" },
+      options
+    );
+  }
+  /**
+   * Move them now and start a fresh period today: the period they were in
+   * closes where the change lands, keeping the usage it had, and the new
+   * plan's full amount opens immediately.
+   *
+   * This moves the customer's anchor, so their renewal day becomes today. It
+   * is the move for a customer starting over — a new contract, a re-signup —
+   * and the only one that can take a customer between plans whose cycles
+   * differ.
+   */
+  restart(customerId, params, options) {
+    return this.change(
+      customerId,
+      { plan: params.plan, effective: "immediate", reconciliation: "reset" },
+      options
+    );
+  }
+  /**
+   * Call off a change that has not landed yet, leaving the customer on the
+   * plan they hold. Naming the plan already held is what supersedes a pending
+   * instruction, so this reads the plan in force and names it back.
+   *
+   * Returns the assignment still in force, or `null` for a customer holding no
+   * plan — who can have nothing pending, since a first assignment always lands
+   * at once.
+   */
+  async cancelScheduledChange(customerId, options) {
+    const current = await this.retrieve(customerId, options);
+    if (current === null) return null;
+    return this.assign(customerId, { plan_id: current.plan_id }, options);
+  }
+  /**
+   * The plan in force now, which is not always the newest instruction: a
+   * change dated ahead does not govern yet.
+   *
+   * `null` when the customer holds no plan. That is a default deny rather than
+   * a failure — they are entitled to nothing — so it is an answer here and not
+   * a thrown `NotFoundError`. A customer who does not exist at all still
+   * throws one.
+   */
+  async retrieve(customerId, options) {
+    try {
+      return await this.#client.request({
+        ...options,
+        method: "GET",
+        path: `/v1/customers/${encodeURIComponent(customerId)}/plan`
+      });
+    } catch (error) {
+      if (error instanceof NotFoundError && error.code === "no_plan_assigned") {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * The change waiting to land, or `null` when none is. At most one is ever
+   * live: a newer instruction supersedes the one before it.
+   *
+   * Read against the assignment in force rather than against the local clock,
+   * so a change landing seconds from now is not reported as already governing.
+   */
+  async pending(customerId, options) {
+    const [current, { data }] = await Promise.all([
+      this.retrieve(customerId, options),
+      this.history(customerId, options)
+    ]);
+    const inForce = current === null ? -Infinity : Date.parse(current.effective_at);
+    return data.find(
+      (a) => a.superseded_at === null && Date.parse(a.effective_at) > inForce
+    ) ?? null;
+  }
+  /** Every instruction, superseded ones included: it is the whole trail. */
+  history(customerId, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/customers/${encodeURIComponent(customerId)}/plan/history`
+    });
+  }
+};
+
+// src/resources/customers.ts
+var Customers = class {
+  /** The plan they hold, and the trail of instructions that got them there. */
+  plan;
+  /** Grants, which sit on top of whatever the plan gives. */
+  allowances;
+  #client;
+  constructor(client) {
+    this.#client = client;
+    this.plan = new CustomerPlan(client);
+    this.allowances = new CustomerAllowances(client);
+  }
+  create(params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: "/v1/customers",
+      body: params
+    });
+  }
+  /** Lean: a listing does not embed the plan. Read one customer for that. */
+  list(params = {}, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: "/v1/customers",
+      query: { include_deleted: params.include_deleted }
+    });
+  }
+  /**
+   * One customer, with the plan they hold. `plan` is the one in force now and
+   * `pending_plan` the change waiting to land, each `null` when there is
+   * none — so knowing what a customer is on costs no second request.
+   */
+  retrieve(id, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/customers/${encodeURIComponent(id)}`
+    });
+  }
+  /**
+   * Resolves the tenant's own identifier, or null, embedding the plan the way
+   * `retrieve` does. The engine answers this as a filtered list, so a miss is
+   * an empty collection rather than a 404.
+   */
+  async retrieveByExternalId(externalId, options) {
+    const { data } = await this.#client.request({
+      ...options,
+      method: "GET",
+      path: "/v1/customers",
+      query: { external_id: externalId }
+    });
+    return data[0] ?? null;
+  }
+  update(id, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "PATCH",
+      path: `/v1/customers/${encodeURIComponent(id)}`,
+      body: params
+    });
+  }
+  /** Soft delete: usage and assignments keep referencing the customer. */
+  delete(id, options) {
+    return this.#client.request({
+      ...options,
+      method: "DELETE",
+      path: `/v1/customers/${encodeURIComponent(id)}`
+    });
+  }
+};
+
+// src/resources/meters.ts
+var Meters = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  create(params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: "/v1/meters",
+      body: params
+    });
+  }
+  list(params = {}, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: "/v1/meters",
+      query: { include_archived: params.include_archived }
+    });
+  }
+  retrieve(id, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/meters/${encodeURIComponent(id)}`
+    });
+  }
+  update(id, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "PATCH",
+      path: `/v1/meters/${encodeURIComponent(id)}`,
+      body: params
+    });
+  }
+  /** Soft delete: plans and usage keep referencing the meter. Idempotent. */
+  archive(id, options) {
+    return this.#client.request({
+      ...options,
+      method: "DELETE",
+      path: `/v1/meters/${encodeURIComponent(id)}`
+    });
+  }
+};
+
+// src/resources/plans.ts
+var PlanAllowances = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  set(planId, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: `/v1/plans/${encodeURIComponent(planId)}/allowances`,
+      body: params
+    });
+  }
+  /** Every version of every meter, newest first — history, not just current. */
+  list(planId, params = {}, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/plans/${encodeURIComponent(planId)}/allowances`,
+      query: { meter_id: params.meter_id }
+    });
+  }
+};
+var Plans = class {
+  allowances;
+  #client;
+  constructor(client) {
+    this.#client = client;
+    this.allowances = new PlanAllowances(client);
+  }
+  /** A new plan grants nothing; attach entitlement with `allowances.set`. */
+  create(params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: "/v1/plans",
+      body: params
+    });
+  }
+  list(params = {}, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: "/v1/plans",
+      query: { include_archived: params.include_archived }
+    });
+  }
+  retrieve(id, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/plans/${encodeURIComponent(id)}`
+    });
+  }
+  update(id, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "PATCH",
+      path: `/v1/plans/${encodeURIComponent(id)}`,
+      body: params
+    });
+  }
+  /**
+   * Stops new assignments without withdrawing capacity from anyone already on
+   * the plan, which is why an archived plan still resolves by id. Idempotent.
+   */
+  archive(id, options) {
+    return this.#client.request({
+      ...options,
+      method: "DELETE",
+      path: `/v1/plans/${encodeURIComponent(id)}`
+    });
+  }
+};
+
+// src/index.ts
+var Meterbase = class {
+  customers;
+  meters;
+  plans;
+  #client;
+  constructor(options) {
+    this.#client = new Client(options);
+    this.customers = new Customers(this.#client);
+    this.meters = new Meters(this.#client);
+    this.plans = new Plans(this.#client);
+  }
+  /**
+   * Asks whether a customer may consume `quantity` of a meter, named by the
+   * tenant's own external id and the meter's key. Absence of entitlement is
+   * not permission: a customer with no plan and no grant is denied.
+   *
+   * This is the gate, and the only call that ever refuses. Run it before the
+   * work; record the work with `track` afterwards.
+   */
+  check(params, options) {
+    return this.#client.request({
+      ...options,
+      method: "POST",
+      path: "/v1/check",
+      body: params
+    });
+  }
+  /**
+   * Records usage that already happened — the tokens were spent, the image
+   * was generated — so it never refuses on capacity. A quantity beyond the
+   * 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.
+   */
+  // `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({
+      ...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
+    });
+  }
+  /** Reports which workspace this key acts for. */
+  whoami(options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: "/v1/whoami"
+    });
+  }
+};
+function idempotencyKey() {
+  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("");
+  }
+  throw new MeterbaseError(
+    "No crypto to generate an idempotency key with: pass `idempotency_key` yourself, or run somewhere `crypto.getRandomValues` exists."
+  );
+}
+
+exports.APIError = APIError;
+exports.AuthenticationError = AuthenticationError;
+exports.ConflictError = ConflictError;
+exports.ConnectionError = ConnectionError;
+exports.CycleChangeRequiresResetError = CycleChangeRequiresResetError;
+exports.IdempotencyConflictError = IdempotencyConflictError;
+exports.InvalidRequestError = InvalidRequestError;
+exports.Meterbase = Meterbase;
+exports.MeterbaseError = MeterbaseError;
+exports.NotFoundError = NotFoundError;
+exports.PermissionDeniedError = PermissionDeniedError;
+exports.RateLimitError = RateLimitError;
+exports.ServerError = ServerError;
+exports.TimeoutError = TimeoutError;
+exports.errorFromResponse = errorFromResponse;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map