@superblocksteam/sdk 2.0.117-next.3 → 2.0.118-next.0

package/src/client.ts

@@ -2796,21 +2796,71 @@ export interface UsageRecordRow {
   source: string;
 }
 
+export interface UserCreditLimit {
+  amountLimitCents: number | null;
+  creditLimit: number | null;
+  id: string;
+  orgId: string;
+  updatedAt: string;
+  updatedBy: string | null;
+  userId: string | null;
+}
+
+export type OrgCreditLimit = Omit<UserCreditLimit, "userId">;
+
+export interface BillingUsageLimitsResponse {
+  limits: UserCreditLimit[];
+  orgLimit: OrgCreditLimit | null;
+}
+
+type BillingUsageLimitValue =
+  | {
+      amountLimitCents: number;
+      creditLimit?: never;
+    }
+  | {
+      amountLimitCents?: never;
+      creditLimit: number;
+    };
+
+export type UpdateUserBillingUsageLimitRequest = BillingUsageLimitValue & {
+  userId: string | null;
+};
+
+export type UpdateOrgBillingUsageLimitRequest = BillingUsageLimitValue;
+
 export interface PlanSummary {
   billingInterval: "annual" | "monthly";
+  builderSeatsAssigned?: number;
+  builderSeatsTotal?: number;
+  contractEnd?: string | null;
+  contractStart?: string | null;
+  contractType?: string | null;
   currentPlanCredits: number;
   currentUsageCredits: number;
   cycleStart: string | null;
   cycleEnd: string | null;
   creditsPerSeat: number | null;
-  pricePerSeatAnnual: number | null;
-  pricePerSeatMonthly: number | null;
-  deployedAppsUsed: number;
-  deployedAppsLimit: number;
-  deployedAppsIncluded: number;
   deployedAppsAdditional: number;
-  deployedAppPriceMonthly: number | null;
   deployedAppPriceAnnual: number | null;
+  deployedAppPriceMonthly: number | null;
+  deployedAppsIncluded: number;
+  deployedAppsLimit: number;
+  deployedAppsUsed: number;
+  deployedAppCostCents?: number | null;
+  dollarCommitAmountCents?: number | null;
+  dollarCommitUsedCents?: number | null;
+  overageAppsEnabled?: boolean;
+  overageCreditsEnabled?: boolean;
+  overageSeatsEnabled?: boolean;
+  pricePerSeatAnnual: number | null;
+  pricePerSeatMonthly: number | null;
+  seatsUnlimited?: boolean;
+  subscriptionStatus: string | null;
+  topupCreditsPurchased: number;
+  topupCreditsUsed: number;
+  usageResetPeriodLimit: number;
+  usageResetPeriodType: "annual" | "contract_term" | "monthly";
 }
 
 export async function fetchBillingUsageDaily({
@@ -2945,6 +2995,139 @@ export async function fetchBillingPlanSummary({
   }
 }
 
+export async function fetchBillingUsageLimits({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+}): Promise<BillingUsageLimitsResponse> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/billing/user-credit-limits`,
+      superblocksBaseUrl,
+    );
+
+    const config: AxiosRequestConfig = {
+      method: "get",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as BillingUsageLimitsResponse;
+  } catch (e: any) {
+    let message: string;
+    if (e instanceof AxiosError) {
+      message =
+        (e.response?.data?.responseMeta?.message as string) ??
+        JSON.stringify(e.response?.data) ??
+        e.response?.statusText ??
+        e?.message;
+    } else {
+      message = `${e?.message ? e?.message : e}`;
+    }
+    throw new Error(`Could not fetch billing usage limits: ${message}`);
+  }
+}
+
+export async function updateUserBillingUsageLimit({
+  amountLimitCents,
+  cliVersion,
+  creditLimit,
+  token,
+  superblocksBaseUrl,
+  userId,
+}: UpdateUserBillingUsageLimitRequest & {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+}): Promise<{ success: boolean }> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/billing/user-credit-limits`,
+      superblocksBaseUrl,
+    );
+
+    const config: AxiosRequestConfig = {
+      method: "put",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+      data: {
+        userId,
+        ...(amountLimitCents !== undefined
+          ? { amountLimitCents }
+          : { creditLimit }),
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as { success: boolean };
+  } catch (e: any) {
+    let message: string;
+    if (e instanceof AxiosError) {
+      message =
+        (e.response?.data?.responseMeta?.message as string) ??
+        JSON.stringify(e.response?.data) ??
+        e.response?.statusText ??
+        e?.message;
+    } else {
+      message = `${e?.message ? e?.message : e}`;
+    }
+    throw new Error(`Could not update user billing usage limit: ${message}`);
+  }
+}
+
+export async function updateOrgBillingUsageLimit({
+  amountLimitCents,
+  cliVersion,
+  creditLimit,
+  token,
+  superblocksBaseUrl,
+}: UpdateOrgBillingUsageLimitRequest & {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+}): Promise<{ success: boolean }> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/billing/user-credit-limits/org`,
+      superblocksBaseUrl,
+    );
+
+    const config: AxiosRequestConfig = {
+      method: "put",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+      data:
+        amountLimitCents !== undefined ? { amountLimitCents } : { creditLimit },
+    };
+    const response = await axios(config);
+    return response.data.data as { success: boolean };
+  } catch (e: any) {
+    let message: string;
+    if (e instanceof AxiosError) {
+      message =
+        (e.response?.data?.responseMeta?.message as string) ??
+        JSON.stringify(e.response?.data) ??
+        e.response?.statusText ??
+        e?.message;
+    } else {
+      message = `${e?.message ? e?.message : e}`;
+    }
+    throw new Error(`Could not update org billing usage limit: ${message}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Knowledge (Facts)
 // ---------------------------------------------------------------------------

package/src/dev-utils/dedupe-async.test.ts

@@ -0,0 +1,151 @@
+// Regression tests for the in-flight dedupe used by the dev-server graceful
+// shutdown path (hq-o55a). The bug being guarded against: multiple signals
+// (SIGINT, SIGTERM, SIGABRT, uncaughtException) fire in rapid succession during
+// shutdown and each handler re-runs cleanup against already-freed native state,
+// surfacing as `double free or corruption (fasttop)` from glibc.
+
+import { describe, expect, it, vi } from "vitest";
+
+import { dedupeAsync } from "./dedupe-async.js";
+
+describe("dedupeAsync", () => {
+  it("invokes the wrapped function exactly once across concurrent calls", async () => {
+    const inner = vi.fn(async () => "ok");
+    const wrapped = dedupeAsync(inner);
+
+    const results = await Promise.all([
+      wrapped(),
+      wrapped(),
+      wrapped(),
+      wrapped(),
+    ]);
+
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(results).toEqual(["ok", "ok", "ok", "ok"]);
+  });
+
+  it("returns the same promise instance to all concurrent callers", () => {
+    const inner = vi.fn(async () => 42);
+    const wrapped = dedupeAsync(inner);
+
+    const p1 = wrapped();
+    const p2 = wrapped();
+
+    expect(p1).toBe(p2);
+  });
+
+  it("invokes onDuplicate for each call after the first", async () => {
+    let resolveInner: (v: string) => void = () => {};
+    const inner = vi.fn(
+      () =>
+        new Promise<string>((resolve) => {
+          resolveInner = resolve;
+        }),
+    );
+    const onDuplicate = vi.fn();
+    const wrapped = dedupeAsync(inner, { onDuplicate });
+
+    const p1 = wrapped();
+    wrapped();
+    wrapped();
+    wrapped();
+
+    expect(onDuplicate).toHaveBeenCalledTimes(3);
+    expect(inner).toHaveBeenCalledTimes(1);
+
+    resolveInner("done");
+    await expect(p1).resolves.toBe("done");
+  });
+
+  it("retains the cached promise after the inner call settles — post-settle callers get the same outcome", async () => {
+    const inner = vi.fn(async () => "shutdown-complete");
+    const wrapped = dedupeAsync(inner);
+
+    await expect(wrapped()).resolves.toBe("shutdown-complete");
+    // Second invocation AFTER the first settled — must NOT re-trigger.
+    await expect(wrapped()).resolves.toBe("shutdown-complete");
+    expect(inner).toHaveBeenCalledTimes(1);
+  });
+
+  it("propagates rejection to all callers without re-running the inner function", async () => {
+    const inner = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const wrapped = dedupeAsync(inner);
+
+    const p1 = wrapped();
+    const p2 = wrapped();
+    const p3 = wrapped();
+
+    await expect(p1).rejects.toThrow(/boom/);
+    await expect(p2).rejects.toThrow(/boom/);
+    await expect(p3).rejects.toThrow(/boom/);
+    expect(inner).toHaveBeenCalledTimes(1);
+  });
+
+  it("retains the cached rejection after the inner call settles — post-settle callers get the same rejection without re-run", async () => {
+    // Guards against a future change that resets `inFlight = null` on
+    // rejection (a plausible "retry on failure" tweak). The shutdown
+    // contract is that BOTH outcomes are sticky — resolve and reject —
+    // because re-entering cleanup after a failed first attempt is what
+    // caused the original double-free. A passing test for the resolve path
+    // alone would let that regression slip through.
+    const inner = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const wrapped = dedupeAsync(inner);
+
+    await expect(wrapped()).rejects.toThrow(/boom/);
+    // Second invocation AFTER the first rejection settled — must NOT
+    // re-trigger and must surface the same rejection.
+    await expect(wrapped()).rejects.toThrow(/boom/);
+    expect(inner).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards args to the inner function on the first call only", async () => {
+    const inner = vi.fn(async (a: number, b: string) => `${a}-${b}`);
+    const wrapped = dedupeAsync(inner);
+
+    const p1 = wrapped(1, "first");
+    // Second call passes different args, but is short-circuited — inner
+    // should NOT be invoked again. The dedupe is intentionally
+    // input-agnostic: shutdown semantics don't depend on the second
+    // signal's arguments.
+    const p2 = wrapped(2, "second");
+
+    await expect(p1).resolves.toBe("1-first");
+    await expect(p2).resolves.toBe("1-first");
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(inner).toHaveBeenCalledWith(1, "first");
+  });
+
+  it("passes the duplicate caller's args to onDuplicate (for source-tagged logging)", async () => {
+    // The dev-server graceful shutdown threads a `source` field through
+    // (signal name, "uncaughtException", "/_sb_disconnect") so the
+    // duplicate-suppression log can tell apart "4 OS signals fired" from
+    // "1 signal fired and cleanup panicked 3 times". The dedupe must
+    // forward each duplicate's own args, not the first caller's.
+    let resolveInner: () => void = () => {};
+    const inner = vi.fn(
+      (arg: { source: string }): Promise<{ source: string }> =>
+        new Promise((resolve) => {
+          resolveInner = () => resolve(arg);
+        }),
+    );
+    const onDuplicate = vi.fn();
+    const wrapped = dedupeAsync(inner, { onDuplicate });
+
+    const p1 = wrapped({ source: "SIGTERM" });
+    wrapped({ source: "SIGINT" });
+    wrapped({ source: "SIGABRT" });
+
+    expect(onDuplicate).toHaveBeenCalledTimes(2);
+    expect(onDuplicate).toHaveBeenNthCalledWith(1, { source: "SIGINT" });
+    expect(onDuplicate).toHaveBeenNthCalledWith(2, { source: "SIGABRT" });
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(inner).toHaveBeenCalledWith({ source: "SIGTERM" });
+
+    resolveInner();
+    await p1;
+  });
+});

package/src/dev-utils/dedupe-async.ts

@@ -0,0 +1,45 @@
+// In-flight call deduper. Wraps an async function so that concurrent invocations
+// share the same promise — subsequent callers get the original in-flight result
+// instead of triggering another execution.
+//
+// After the wrapped function settles (resolves OR rejects) the cached promise is
+// retained so all post-settle callers receive the same outcome. There is no
+// reset path: callers that want to "run again later" should use a fresh
+// `dedupeAsync` instance.
+//
+// Used by the dev-server graceful shutdown path (hq-o55a). Multiple signals
+// (SIGINT, SIGTERM, SIGABRT, uncaughtException) can fire in rapid succession
+// during shutdown. Without a dedupe, every handler re-runs lockService /
+// vite / httpServer cleanup against already-freed native state, which surfaces
+// as `double free or corruption (fasttop)` from glibc and SIGABRT killing the
+// process before it can exit cleanly.
+
+export interface DedupeAsyncOptions<TArgs extends unknown[]> {
+  /**
+   * Optional callback invoked when a duplicate call is detected. The first
+   * caller's invocation runs normally; this fires for the 2nd, 3rd, …
+   * Useful for logging "shutdown already in progress; ignoring duplicate
+   * signal".
+   *
+   * Receives the *duplicate* call's args (not the first call's). The first
+   * call's args are what the wrapped function actually ran with — duplicates
+   * are intentionally short-circuited and their args are dropped from
+   * execution but surfaced here for logging.
+   */
+  onDuplicate?: (...args: TArgs) => void;
+}
+
+export function dedupeAsync<TArgs extends unknown[], TResult>(
+  fn: (...args: TArgs) => Promise<TResult>,
+  options: DedupeAsyncOptions<TArgs> = {},
+): (...args: TArgs) => Promise<TResult> {
+  let inFlight: Promise<TResult> | null = null;
+  return (...args: TArgs) => {
+    if (inFlight) {
+      options.onDuplicate?.(...args);
+      return inFlight;
+    }
+    inFlight = fn(...args);
+    return inFlight;
+  };
+}

package/src/dev-utils/dev-server-metrics.mts

@@ -0,0 +1,252 @@
+/**
+ * Dev-server connection-phase metrics.
+ *
+ * Records counters and histograms for the dev-server endpoints that the editor
+ * and SABS hit during a live-edit connection: `/_sb_health`, `/_sb_connect`,
+ * `/_sb_activate`, `/_sb_disconnect`, `/_sb_status`, `/_sb_activity`, plus
+ * WebSocket upgrades, Vite eager-init, and warm-standby activation.
+ *
+ * Metrics are scoped to the dev-server's existing OTel pipeline. When telemetry
+ * has not yet initialized (warm-standby pre-activation), record calls are
+ * buffered and replayed by `flush()` once `configureTelemetry` completes, so
+ * warm-standby observations are not silently dropped into the no-op meter.
+ */
+
+import { isTelemetryInitialized } from "@superblocksteam/telemetry";
+
+import { getMeter } from "../telemetry/index.js";
+
+/** Dev-server endpoints that produce per-request metrics. */
+export type DevServerEndpoint =
+  | "_sb_health"
+  | "_sb_connect"
+  | "_sb_activate"
+  | "_sb_disconnect"
+  | "_sb_status"
+  | "_sb_activity"
+  | "_sb_persist"
+  | "_sb_ready";
+
+/**
+ * Allowlisted HTTP methods recorded as the `method` metric label. Anything
+ * outside this set — `req.method` is client-controlled, and `/_sb_health` is
+ * unauthenticated — is bucketed as `'OTHER'` to keep label cardinality bounded.
+ */
+const ALLOWED_METHODS: ReadonlySet<string> = new Set([
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+]);
+
+function sanitizeMethod(method: string): string {
+  const upper = method.toUpperCase();
+  return ALLOWED_METHODS.has(upper) ? upper : "OTHER";
+}
+
+/**
+ * Coarse failure type for dev-server endpoint outcomes. Distinct from raw HTTP
+ * status so dashboards can filter by reason without high-cardinality labels.
+ */
+export type DevServerFailureType =
+  | "none"
+  | "auth"
+  | "validation"
+  | "branch_mismatch"
+  | "vite_init"
+  | "internal";
+
+/**
+ * Outcome of the warm-standby activation handshake.
+ *
+ *   accepted  - 200 OK, transitioning to full server
+ *   rejected  - 400/413 (validation, body too large)
+ *   error     - JSON parse / unexpected exception
+ */
+export type WarmActivationOutcome = "accepted" | "rejected" | "error";
+
+/**
+ * Soft cap on buffered pre-init events. Warm-standby reasonably emits ~1
+ * `recordWarmPrewarm` + ~1 `recordWarmActivation` before activation, so the
+ * cap is generously above the expected load — it exists only to bound memory
+ * if `flush()` is somehow never called.
+ */
+const MAX_BUFFERED_EVENTS = 256;
+
+/**
+ * Records dev-server connection-phase metrics.
+ *
+ * Calls made before `configureTelemetry` completes are queued and replayed by
+ * `flush()` once telemetry is online. Without this, warm-standby observations
+ * are routed through `getMeter()`'s no-op fallback meter and silently dropped
+ * — defeating the metric's purpose, since warm activation is exactly the path
+ * we want to observe. The buffer is bounded to bound memory; instruments are
+ * still NOT cached, so each replayed call resolves a fresh meter.
+ */
+class DevServerMetrics {
+  /**
+   * Pre-init replay queue. Entries are bound `() => void` recorders that close
+   * over their args at call time, so labels are captured even if the buffer is
+   * drained much later.
+   */
+  private bufferedRecorders: Array<() => void> = [];
+
+  /**
+   * Routes a recorder to the live OTel meter when telemetry is up, or buffers
+   * it for replay when telemetry has not yet initialized.
+   */
+  private record(recorder: () => void): void {
+    if (isTelemetryInitialized()) {
+      recorder();
+      return;
+    }
+    if (this.bufferedRecorders.length >= MAX_BUFFERED_EVENTS) {
+      // Drop the oldest event rather than the new one — the most recent
+      // observations are typically the most informative for an investigator.
+      this.bufferedRecorders.shift();
+    }
+    this.bufferedRecorders.push(recorder);
+  }
+
+  /**
+   * Replays buffered recorders against the (now-initialized) meter and clears
+   * the queue. Idempotent — safe to call multiple times. Callers should invoke
+   * this immediately after `configureTelemetry()` resolves.
+   *
+   * No-ops if telemetry did not actually come up (e.g., `configureTelemetry`
+   * returned `false` due to a missing config or an internal init failure).
+   * Draining the buffer through a still-no-op meter would silently lose every
+   * observation AND clear the queue, so a later successful re-init via
+   * `onTokenReceived` could not recover them. Keeping the buffer intact lets
+   * a subsequent `flush()` call replay them once telemetry is genuinely live.
+   */
+  flush(): void {
+    if (!isTelemetryInitialized()) {
+      return;
+    }
+    if (this.bufferedRecorders.length === 0) {
+      return;
+    }
+    const events = this.bufferedRecorders;
+    this.bufferedRecorders = [];
+    for (const e of events) {
+      e();
+    }
+  }
+
+  /**
+   * Records the outcome of a dev-server HTTP endpoint request.
+   */
+  recordEndpoint(
+    endpoint: DevServerEndpoint,
+    method: string,
+    status: number,
+    durationMs: number,
+    failureType: DevServerFailureType = "none",
+  ): void {
+    const labels = {
+      endpoint,
+      method: sanitizeMethod(method),
+      status: String(status),
+      failure_type: failureType,
+    };
+    this.record(() => {
+      const meter = getMeter();
+      meter
+        .createCounter("dev_server_endpoint_requests_total", {
+          description:
+            "Count of dev-server endpoint requests by endpoint, status, and failure type.",
+        })
+        .add(1, labels);
+      meter
+        .createHistogram("dev_server_endpoint_duration_ms", {
+          description:
+            "Latency of dev-server endpoint requests in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs, labels);
+    });
+  }
+
+  /**
+   * Records a WebSocket upgrade attempt against the dev-server's HTTP socket.
+   */
+  recordSocketUpgrade(outcome: "accepted" | "rejected"): void {
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_socket_upgrade_total", {
+          description:
+            "Count of WebSocket upgrade attempts against the dev-server HTTP socket.",
+        })
+        .add(1, { outcome });
+    });
+  }
+
+  /**
+   * Records the duration and outcome of Vite eager-init (the call that creates
+   * the user-facing Vite server during /_sb_connect ramp-up).
+   */
+  recordViteEagerInit(durationMs: number, outcome: "success" | "error"): void {
+    this.record(() => {
+      getMeter()
+        .createHistogram("dev_server_vite_eager_init_duration_ms", {
+          description:
+            "Duration of eager Vite server initialization in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs, { outcome });
+    });
+  }
+
+  /**
+   * Records the duration and outcome of warm-pod Vite dep-cache pre-warm.
+   */
+  recordWarmPrewarm(durationMs: number, outcome: "success" | "error"): void {
+    this.record(() => {
+      getMeter()
+        .createHistogram("dev_server_warm_prewarm_duration_ms", {
+          description:
+            "Duration of warm-standby Vite dep-cache pre-warm in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs, { outcome });
+    });
+  }
+
+  /**
+   * Records a warm-standby activation request outcome.
+   */
+  recordWarmActivation(outcome: WarmActivationOutcome): void {
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_warm_activation_total", {
+          description:
+            "Count of warm-standby /_sb_activate requests by outcome.",
+        })
+        .add(1, { outcome });
+    });
+  }
+
+  /**
+   * Records the time from receiving a successful /_sb_activate POST to the
+   * full Express dev-server being attached to the warm HTTP server (the
+   * "no-port-gap" handoff window — gateways see 502s if this stretches).
+   */
+  recordWarmHandoff(durationMs: number): void {
+    this.record(() => {
+      getMeter()
+        .createHistogram("dev_server_warm_activation_handoff_duration_ms", {
+          description:
+            "Time from /_sb_activate acceptance to full dev server attached, in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs);
+    });
+  }
+}
+
+/** Process-wide dev-server metrics singleton. */
+export const devServerMetrics = new DevServerMetrics();