@superblocksteam/sdk 2.0.129-next.0 → 2.0.130-next.0

package/src/cli-replacement/automatic-upgrades.ts

@@ -15,6 +15,7 @@ import {
 } from "@superblocksteam/shared";
 import {
   bucketNpmRegistryHost,
+  recordNpmInstall,
   redactNpmRegistryHostsFromText,
 } from "@superblocksteam/telemetry";
 import type { LockService } from "@superblocksteam/vite-plugin-file-sync/lock-service";
@@ -31,6 +32,9 @@ import {
   clearCliVersionCache,
 } from "./version-detection.js";
 
+// Child exit code that asks the `superblocks dev` parent supervisor to re-exec
+// the dev server after the CLI upgrades its own on-disk binary. Full exit-code
+// contract: packages/cli/packages/cli/src/commands/dev-parent.mts.
 export const AUTO_UPGRADE_EXIT_CODE = 99;
 
 /**
@@ -172,6 +176,12 @@ async function upgradeCliWithOclif(targetVersion: string): Promise<boolean> {
   }
 }
 
+// Returns `true` when an install command actually ran and post-install
+// validation passed (every other failure throws). Returns `false` only when no
+// global install command could be resolved for the detected package manager — a
+// no-op the caller marks as a failed span WITHOUT throwing, so the live-edit
+// pod degrades on the current version instead of crash-looping. Proper graceful
+// degrade + surfacing the failed upgrade to the user is tracked by APPS-4457.
 async function upgradeCliWithPackageManager(
   pm: DetectResult,
   targetVersion: string,
@@ -181,7 +191,7 @@ async function upgradeCliWithPackageManager(
   // `.superblocks/logs`). Optional so callers/tests that don't care keep
   // npm's default `_logs` location.
   logsDir?: string,
-): Promise<void> {
+): Promise<boolean> {
   const packageName = alias
     ? `@superblocksteam/cli@npm:${alias}@${targetVersion}`
     : `@superblocksteam/cli@${targetVersion}`;
@@ -191,12 +201,57 @@ async function upgradeCliWithPackageManager(
   const installCommand = resolveCommand(pm.agent, "global", installArgs);
 
   if (!installCommand) {
+    // APPS-4544 (Bugbot 613adfc7): we couldn't even build a global install
+    // command for the detected package manager, so no upgrade happened.
+    // Before this PR added the `upgradeCli` span `outcome` attribute and the
+    // `superblocks.npm.install.*` metric, this no-op left no telemetry: the
+    // span kept its default `outcome=success` and no install metric was
+    // emitted, so an auto-upgrade that did nothing looked successful.
+    //
+    // Emit a failure sample so the histogram carries a `runner="auto_upgrade"`
+    // failure sample for this path, then return `false` so the caller flips
+    // the `upgradeCli` span to `outcome=failure`. `durationMs` is 0 because no
+    // install process ran; `outcome="other"` mirrors the unclassified-failure
+    // fallback used by the exec/validation paths below.
+    //
+    // We deliberately do NOT throw: a rejected upgrade promise routes through
+    // `dev.mts` to `process.exit(1)`, crash-looping the live-edit pod. The
+    // no-op dev-server restart that still follows (`cliUpdated` is set
+    // unconditionally at enqueue time in `checkVersionsAndWritePackageJson`),
+    // plus degrading gracefully (continue on the current version) and
+    // surfacing the failed upgrade to the user, are tracked by APPS-4457.
     logger.error("Could not determine how to upgrade Superblocks packages.");
-    return;
+    recordNpmInstall({
+      runner: "auto_upgrade",
+      outcome: "other",
+      configured: hasAnyRegistryConfigured ?? false,
+      registryHost: undefined,
+      durationMs: 0,
+    });
+    return false;
   }
 
   const { command, args } = installCommand;
   logger.info(`Running ${command} ${args.join(" ")}...`);
+  // APPS-4544: emit `superblocks.npm.install.*` for the CLI auto-upgrade
+  // install. Until now this path's only failure signal was a structured log
+  // line + the rejected promise; metrics/dashboards distinguishing a
+  // perimeter-blocked upgrade from a working one had no `runner="auto_upgrade"`
+  // facet because no call site emitted it. `installStart` covers exec +
+  // post-install version validation so the histogram answers the operator's
+  // real question ("how long did the upgrade take end-to-end"), not just
+  // "how long did pnpm spend".
+  //
+  // `outcome` / `registryHost` are mutated from inside the exec callback
+  // because that's where the classifier runs; the `finally` then emits with
+  // whatever the callback (or a post-install validation throw below) left
+  // behind. `recordNpmInstall` itself coerces `outcome` through
+  // `normalizeInstallOutcome` and `registryHost` through `bucketNpmRegistryHost`,
+  // so raw `NpmInstallBlocked.reason` / hostnames can't leak past the emit
+  // boundary even if a future caller forgets to pre-sanitize.
+  const installStart = Date.now();
+  let outcome: string = "success";
+  let registryHost: string | undefined;
   let resolver: (value: void | PromiseLike<void>) => void;
   let rejecter: (reason?: any) => void;
   const promise = new Promise<void>((resolve, reject) => {
@@ -233,6 +288,21 @@ async function upgradeCliWithPackageManager(
           requestedPackages: [{ name: packageName }],
           hasAnyRegistryConfigured,
         });
+        // Surface the structured `NpmInstallBlocked.reason` (e.g.
+        // `registry_unreachable`, `registry_auth_failed`) and raw host to
+        // the install metric below; the emitter coerces both at the emit
+        // boundary (`normalizeInstallOutcome` / `bucketNpmRegistryHost`),
+        // so a reason that isn't in `NPM_INSTALL_OUTCOMES` folds to
+        // `other` and a private host buckets to `private`. When the
+        // classifier doesn't match (network glitch, lockfile conflict, …)
+        // we still need to flip outcome off `success`, since the install
+        // did fail; default to `other` so the metric reflects the failure.
+        outcome = blocked?.reason ?? "other";
+        // `blocked?.registryHost` is already `string | undefined` (optional
+        // chaining yields `undefined` when `blocked` is null, and
+        // `NpmInstallBlocked.registryHost` is `readonly registryHost?: string`),
+        // so no `?? undefined` fallback is needed.
+        registryHost = blocked?.registryHost;
         if (blocked) {
           // Structured fields are grep-able from the message body because
           // the local logger contract limits the meta arg to
@@ -296,28 +366,61 @@ async function upgradeCliWithPackageManager(
     logger.warn(data);
   });
 
-  // Wait for the install to complete, then validate the version
-  await promise;
+  try {
+    // Wait for the install to complete, then validate the version
+    await promise;
 
-  // Clear cache to force actual version detection (not just returning cached value)
-  clearCliVersionCache();
+    // Clear cache to force actual version detection (not just returning cached value)
+    clearCliVersionCache();
 
-  const currentCliInfo = await getCurrentCliVersion();
-  if (!currentCliInfo) {
-    throw new Error("Could not get validate CLI version post-install");
-  }
+    const currentCliInfo = await getCurrentCliVersion();
+    if (!currentCliInfo) {
+      throw new Error("Could not get validate CLI version post-install");
+    }
 
-  if (currentCliInfo.version !== targetVersion) {
-    throw new Error(
-      `CLI version mismatch after upgrade: ${currentCliInfo.version} !== ${targetVersion}`,
-    );
-  }
+    if (currentCliInfo.version !== targetVersion) {
+      throw new Error(
+        `CLI version mismatch after upgrade: ${currentCliInfo.version} !== ${targetVersion}`,
+      );
+    }
 
-  // Now that we've validated, cache the correct version (avoids re-detection on next call)
-  clearCliVersionCache({ version: targetVersion, alias });
+    // Now that we've validated, cache the correct version (avoids re-detection on next call)
+    clearCliVersionCache({ version: targetVersion, alias });
+
+    // This log line is used to end the upgrade spinner
+    logger.info(`Successfully upgraded packages to ${targetVersion}`);
+  } catch (err) {
+    // If outcome is still "success", the install itself succeeded and we
+    // failed during post-install validation (missing binary / version
+    // mismatch). The user-visible effect is the same — auto-upgrade
+    // failed — so the metric flips to `other`. Exec-time failures already
+    // set outcome from the classified `NpmInstallBlocked.reason` (or
+    // `other` for unclassified errors) in the callback above.
+    if (outcome === "success") {
+      outcome = "other";
+    }
+    throw err;
+  } finally {
+    // Both the happy path and every throw above (exec failure → callback
+    // sets outcome, post-install validation throw → catch sets outcome to
+    // `other`) flow through here. The earlier `resolveCommand` failure
+    // returns before `installStart`, so it never reaches this `finally`; it
+    // emits its own `outcome="other"` failure sample inline (with
+    // `durationMs: 0`, since no install ran) so that path isn't a metric gap
+    // either. No double-emit results because that early return skips this block.
+    recordNpmInstall({
+      runner: "auto_upgrade",
+      registryHost,
+      outcome,
+      configured: hasAnyRegistryConfigured ?? false,
+      durationMs: Date.now() - installStart,
+    });
+  }
 
-  // This log line is used to end the upgrade spinner
-  logger.info(`Successfully upgraded packages to ${targetVersion}`);
+  // Reached only when the install ran and post-install validation passed
+  // (every failure above throws). Signals the caller that a real upgrade
+  // happened so it leaves the `upgradeCli` span `outcome=success`.
+  return true;
 }
 
 export async function checkVersionsAndWritePackageJson(
@@ -437,49 +540,143 @@ export async function checkVersionsAndWritePackageJson(
           const cliUpgradePromise = traceFunction({
             name: "upgradeCli",
             tracer,
-            fn: async () => {
-              logger.info(
-                `Beginning CLI upgrade from ${currentCliInfo.version} to ${targetVersions.cli}`,
-              );
-              const oclifUpgradeSucceeded = await traceFunction({
-                name: "upgradeCliWithOclif",
-                tracer,
-                fn: async () => {
-                  return await upgradeCliWithOclif(targetVersions.cli);
-                },
-              });
-              if (!oclifUpgradeSucceeded) {
-                logger.info(`Falling back to package manager upgrade for CLI`);
-                await traceFunction({
-                  name: "upgradePackageWithPackageManager - cli",
+            // APPS-4544: capture the span so the `outcome` attribute can be
+            // set in `finally` below. Adds a single trace-side fact so
+            // operators can correlate a failed upgrade span with the pod
+            // that crash-looped, complementing the
+            // `superblocks.npm.install.*` metric the package-manager and
+            // oclif paths emit below.
+            fn: async (span) => {
+              let outcome: "success" | "failure" = "success";
+              try {
+                logger.info(
+                  `Beginning CLI upgrade from ${currentCliInfo.version} to ${targetVersions.cli}`,
+                );
+                const oclifStart = Date.now();
+                const oclifUpgradeSucceeded = await traceFunction({
+                  name: "upgradeCliWithOclif",
                   tracer,
                   fn: async () => {
-                    await upgradeCliWithPackageManager(
-                      packageManager,
-                      targetVersions.cli,
-                      currentCliInfo.alias,
-                      undefined,
-                      superblocksLogsPath(appDir),
-                    );
+                    return await upgradeCliWithOclif(targetVersions.cli);
                   },
                 });
-                cliUpdated = true;
+                if (oclifUpgradeSucceeded) {
+                  // APPS-4544: oclif succeeded outright, so the package
+                  // manager fallback below is skipped — record the
+                  // upgrade in `superblocks.npm.install.*` here so the
+                  // dashboard's "auto-upgrade succeeded" count includes
+                  // oclif-channel installs. Failures and "not updatable"
+                  // both flow through the fallback, which already
+                  // records the outcome with the correct attributes
+                  // pulled from the classifier; double-emitting from
+                  // both branches would double-count those failures.
+                  recordNpmInstall({
+                    runner: "auto_upgrade",
+                    outcome: "success",
+                    // oclif's update channel is the public superblocks
+                    // tarball location (not a customer-configured npm
+                    // registry), so `configured` is false here even
+                    // when the app shell has a private registry — the
+                    // CLI binary upgrade does not flow through that
+                    // registry, only library/dependency installs do.
+                    configured: false,
+                    // oclif resolves its tarball via its update channel,
+                    // not a configurable npm registry, so there's no
+                    // single host to attribute the install to. Leave
+                    // unset and let `bucketNpmRegistryHost` map it to
+                    // `unknown` at the emit boundary.
+                    registryHost: undefined,
+                    durationMs: Date.now() - oclifStart,
+                  });
+                  // Operator log anchor symmetric with the package-manager
+                  // path's "Successfully upgraded packages to ..." line: the
+                  // oclif branch records a `runner=auto_upgrade, outcome=success`
+                  // metric but, without this, left no log entry to correlate
+                  // the increment against on the oclif channel.
+                  logger.info(
+                    `Successfully upgraded CLI to ${targetVersions.cli} via oclif`,
+                  );
+                } else {
+                  logger.info(
+                    `Falling back to package manager upgrade for CLI`,
+                  );
+                  const cliUpgradeRan = await traceFunction({
+                    name: "upgradePackageWithPackageManager - cli",
+                    tracer,
+                    fn: async () => {
+                      return await upgradeCliWithPackageManager(
+                        packageManager,
+                        targetVersions.cli,
+                        currentCliInfo.alias,
+                        undefined,
+                        superblocksLogsPath(appDir),
+                      );
+                    },
+                  });
+                  if (!cliUpgradeRan) {
+                    // No global install command could be resolved → the CLI
+                    // upgrade was a no-op (the failure metric was already
+                    // emitted inline). Flip the span to `failure` so the trace
+                    // is accurate, but do NOT throw: throwing routes through
+                    // `dev.mts` to `process.exit(1)` and crash-loops the pod.
+                    // The no-op dev-server restart that still follows
+                    // (`cliUpdated = true` below), graceful degrade, and user
+                    // surfacing of the failed upgrade are tracked by APPS-4457.
+                    outcome = "failure";
+                  }
+                }
+                // The freshly fetched tarball may ship bundled lockfiles with
+                // stale public-host `resolved` URLs; strip them so the next
+                // install does not bypass the active registry. Non-fatal —
+                // a failed post-step must not crash the pod after a working
+                // upgrade, and (APPS-4544) must not flip the span outcome
+                // to `failure` either, since the actual upgrade succeeded.
+                // The inner traceFunction still records the strip-level
+                // exception on its own span, so we don't lose the signal.
+                try {
+                  await traceFunction({
+                    name: "stripUpgradedCliLockfiles",
+                    tracer,
+                    fn: async () => {
+                      await stripUpgradedCliLockfiles(logger);
+                    },
+                  });
+                } catch (stripErr) {
+                  logger.warn(
+                    `stripUpgradedCliLockfiles failed (non-fatal): ${
+                      isNativeError(stripErr) ? stripErr.message : stripErr
+                    }`,
+                  );
+                }
+              } catch (err) {
+                outcome = "failure";
+                throw err;
+              } finally {
+                // Closed enum string keeps the trace attribute
+                // queryable in TraceQL without cardinality concerns;
+                // `traceFunction` already records the exception itself
+                // via `recordException`, so this attribute is just a
+                // semantic label for grouping.
+                span.setAttribute("outcome", outcome);
               }
-              // The freshly fetched tarball may ship bundled lockfiles with
-              // stale public-host `resolved` URLs; strip them so the next
-              // install does not bypass the active registry. Non-fatal — a
-              // failed post-step must not crash the pod after a working
-              // upgrade.
-              await traceFunction({
-                name: "stripUpgradedCliLockfiles",
-                tracer,
-                fn: async () => {
-                  await stripUpgradedCliLockfiles(logger);
-                },
-              });
             },
           });
           upgradePromises.push(cliUpgradePromise);
+          // APPS-4554: mark the CLI upgrade as pending SYNCHRONOUSLY here,
+          // not inside the async promise above. `dev.mts` reads
+          // `result.cliUpdated` as a value snapshot immediately after this
+          // function returns (to decide whether to restart the dev server),
+          // but `cliUpgradePromise` suspends at its first `await exec(...)`
+          // and resolves long after the return — so a `cliUpdated = true`
+          // set inside either the oclif or package-manager branch never
+          // reaches the returned snapshot. Setting it at schedule time means
+          // "a CLI upgrade was enqueued; restart once it succeeds." The
+          // success gate stays in `dev.mts`, which awaits this promise via
+          // `joinPackageUpgrade` before restarting and exits (no restart) if
+          // the upgrade rejects. This fixes both the oclif-success path
+          // (Bugbot: it set the flag in neither branch reliably) and the
+          // pre-existing package-manager race.
+          cliUpdated = true;
         }
 
         // Skip if we're in local development

package/src/cli-replacement/dev.mts

@@ -1190,27 +1190,26 @@ export async function dev(options: {
             // auto-upgrade fires. With the file in place, the auto-upgrade's
             // `npm install -g @superblocksteam/cli@…` resolves through the
             // customer's private registry instead of `registry.npmjs.org`.
-            await tracer.startActiveSpan("syncHomeNpmrc", async (span) => {
+            // `syncHomeNpmrc` owns its own `npm_registry.sync_home_npmrc`
+            // span (APPS-4378), so no outer span is created here.
+            if (!aiService) {
+              logger.info(
+                "[home-npmrc] skipped: AiService unavailable at startup",
+              );
+            } else {
               try {
-                if (!aiService) {
-                  logger.info(
-                    "[home-npmrc] skipped: AiService unavailable at startup",
-                  );
-                  return;
-                }
                 await syncHomeNpmrc({
                   npmRegistryClient: aiService.getNpmRegistryClient(),
                   logger,
+                  orgId: currentUser.user.currentOrganizationId,
                 });
               } catch (error) {
                 logger.warn(
                   "[home-npmrc] sync step failed unexpectedly; ~/.superblocks/npmrc left untouched",
                   getErrorMeta(error),
                 );
-              } finally {
-                span.end();
               }
-            });
+            }
 
             let hasCliUpdated = false;
             let upgradePromises: Promise<void>[] = [];

package/src/cli-replacement/home-npmrc.mts

@@ -2,6 +2,14 @@ import { mkdir } from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import { trace } from "@opentelemetry/api";
+
+import {
+  bucketNpmRegistryHost,
+  NPM_REGISTRY_SPAN,
+  NPM_REGISTRY_SPAN_ATTR,
+  withNpmRegistrySpan,
+} from "@superblocksteam/telemetry";
 import {
   type NpmRegistryClient,
   type NpmRegistryFetchResult,
@@ -177,6 +185,12 @@ export interface SyncHomeNpmrcDeps {
    * leave it unset.
    */
   homeDir?: string;
+  /**
+   * Organization id, surfaced on the `npm_registry.sync_home_npmrc` span
+   * (per-trace context, never a metric label). Absent in tests / when no org
+   * context is available at the call site.
+   */
+  orgId?: string;
 }
 
 /**
@@ -230,6 +244,28 @@ export interface SyncHomeNpmrcDeps {
  */
 export async function syncHomeNpmrc(
   deps: SyncHomeNpmrcDeps,
+): Promise<SyncHomeNpmrcResult> {
+  // `npm_registry.sync_home_npmrc` span (APPS-4378). org_id rides on the span;
+  // the precise 5-value outcome and resolved `source` are attached once the
+  // sync resolves (registry_host is set inside the impl, after the fetch).
+  return withNpmRegistrySpan(
+    NPM_REGISTRY_SPAN.SYNC_HOME_NPMRC,
+    deps.orgId ? { [NPM_REGISTRY_SPAN_ATTR.ORG_ID]: deps.orgId } : {},
+    async (span) => {
+      const result = await syncHomeNpmrcImpl(deps);
+      span.setAttributes({
+        [NPM_REGISTRY_SPAN_ATTR.OUTCOME]: result.outcome,
+        ...(result.source
+          ? { [NPM_REGISTRY_SPAN_ATTR.SOURCE]: result.source }
+          : {}),
+      });
+      return result;
+    },
+  );
+}
+
+async function syncHomeNpmrcImpl(
+  deps: SyncHomeNpmrcDeps,
 ): Promise<SyncHomeNpmrcResult> {
   const targetPath = superblocksNpmrcPath(deps.homeDir);
   const backupPath = superblocksNpmrcBackupPath(deps.homeDir);
@@ -250,6 +286,15 @@ export async function syncHomeNpmrc(
     return { outcome: "error", path: targetPath };
   }
 
+  // Attach the bucketed registry_host to the active sync span now that the
+  // config has resolved (the default registry URL is only known here).
+  trace
+    .getActiveSpan()
+    ?.setAttribute(
+      NPM_REGISTRY_SPAN_ATTR.REGISTRY_HOST,
+      bucketNpmRegistryHost(result.config.default?.url),
+    );
+
   if (result.source === "unreachable") {
     deps.logger.warn(
       `${LOG_PREFIX} registry server unreachable with no cached config; ~/.superblocks/npmrc left unchanged`,

package/src/client.billing-usage.test.ts

@@ -0,0 +1,73 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { fetchBillingUsageRecordsResponse } from "./client.js";
+
+const { mockAxios } = vi.hoisted(() => ({
+  mockAxios: vi.fn(),
+}));
+
+vi.mock("axios", async () => {
+  const actual = await vi.importActual("axios");
+  return {
+    ...actual,
+    default: mockAxios,
+  };
+});
+
+describe("fetchBillingUsageRecordsResponse", () => {
+  beforeEach(() => {
+    mockAxios.mockReset();
+  });
+
+  it("returns the full billing usage records payload", async () => {
+    const payload = {
+      agentUsage: [
+        { agentId: "agent-1", name: "Support agent", creditsUsed: 50 },
+      ],
+      applicationUsageRows: [
+        {
+          applicationId: "00000000-0000-4000-8000-000000000001",
+          applicationName: "Operations",
+          creditsUsed: 75,
+          usageType: "ai_credits",
+        },
+      ],
+      dollarLedgerRows: [
+        {
+          amountCents: 1234,
+          applicationId: "app-1",
+          applicationName: "Operations",
+          chargeKind: "committed",
+          creditsUsed: 62,
+          date: "2026-03-24",
+          email: "alice@example.com",
+          entryType: "ai_credit_debit",
+          name: "Alice",
+          usageType: "ai_credits",
+        },
+      ],
+      rows: [
+        {
+          actorId: "user-1",
+          actorType: "user",
+          creditsUsed: 100,
+          date: "2026-03-24",
+          email: "alice@example.com",
+          name: "Alice",
+          source: "seat",
+        },
+      ],
+    };
+    mockAxios.mockResolvedValue({ data: { data: payload } });
+
+    await expect(
+      fetchBillingUsageRecordsResponse({
+        cliVersion: "1.2.3",
+        endDate: "2026-03-25",
+        startDate: "2026-03-24",
+        superblocksBaseUrl: "https://staging.superblocks.com",
+        token: "test-token",
+      }),
+    ).resolves.toEqual(payload);
+  });
+});

package/src/client.ts

@@ -2789,6 +2789,8 @@ export interface DailyUsageRow {
 }
 
 export interface UsageRecordRow {
+  actorId?: string;
+  actorType?: "ai_agent" | "user";
   date: string;
   email: string;
   name: string;
@@ -2796,6 +2798,42 @@ export interface UsageRecordRow {
   source: string;
 }
 
+export interface AgentUsageRow {
+  agentId: string;
+  name: string;
+  creditsUsed: number;
+}
+
+export interface ApplicationUsageRow {
+  applicationId: string;
+  applicationName: string;
+  creditsUsed: number;
+  usageType: "ai_credits";
+}
+
+export interface DollarLedgerRow {
+  amountCents: number;
+  applicationId: string | null;
+  applicationName: string | null;
+  chargeKind: "committed" | "overage";
+  creditsUsed: number | null;
+  date: string;
+  email: string | null;
+  entryType: string;
+  name: string | null;
+  usageType: "ai_credits" | "deployed_app";
+}
+
+export interface BillingUsageRecordsResponse {
+  agentUsage?: AgentUsageRow[];
+  applicationUsageRows?: ApplicationUsageRow[];
+  dollarCommitUsedCents?: number;
+  dollarLedgerRows?: DollarLedgerRow[];
+  enterpriseBillingWindows?: unknown[];
+  rows: UsageRecordRow[];
+  seatAssignments?: unknown[];
+}
+
 export interface UserCreditLimit {
   amountLimitCents: number | null;
   creditLimit: number | null;
@@ -2922,6 +2960,29 @@ export async function fetchBillingUsageRecords({
   startDate: string;
   endDate: string;
 }): Promise<UsageRecordRow[]> {
+  const response = await fetchBillingUsageRecordsResponse({
+    cliVersion,
+    token,
+    superblocksBaseUrl,
+    startDate,
+    endDate,
+  });
+  return response.rows;
+}
+
+export async function fetchBillingUsageRecordsResponse({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  startDate,
+  endDate,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  startDate: string;
+  endDate: string;
+}): Promise<BillingUsageRecordsResponse> {
   try {
     const url = new URL(
       `${BASE_SERVER_API_URL_V1}/billing/usage-records`,
@@ -2939,7 +3000,11 @@ export async function fetchBillingUsageRecords({
       },
     };
     const response = await axios(config);
-    return response.data.data.rows as UsageRecordRow[];
+    const data = response.data.data as Partial<BillingUsageRecordsResponse>;
+    if (!Array.isArray(data.rows)) {
+      throw new Error("Billing usage records response did not include rows");
+    }
+    return data as BillingUsageRecordsResponse;
   } catch (e: any) {
     let message: string;
     if (e instanceof AxiosError) {