@superblocksteam/sdk 2.0.117 → 2.0.118-next.0

package/src/index.ts

@@ -7,13 +7,18 @@ export {
   type CodeModeApplicationWrapper,
   type CreateApplicationResult,
   type CurrentBranch,
+  type BillingUsageLimitsResponse,
   type DailyUsageRow,
   type GetCommitsResponseBody,
   type IntegrationFilters,
   type IntegrationSummary,
   type MultiPageApplicationWrapper,
   type MultiPageApplicationWrapperWithComponents,
+  type OrgCreditLimit,
   type PlanSummary,
+  type UpdateOrgBillingUsageLimitRequest,
+  type UpdateUserBillingUsageLimitRequest,
+  type UserCreditLimit,
   type UsageRecordRow,
 } from "./client.js";
 
@@ -65,6 +70,12 @@ export { AUTO_UPGRADE_EXIT_CODE } from "./cli-replacement/automatic-upgrades.js"
 export { RESTART_EXIT_CODE } from "./dev-utils/dev-server.mjs";
 
 export { createDevServer, preWarmViteCache } from "./dev-utils/dev-server.mjs";
+export {
+  devServerMetrics,
+  type DevServerEndpoint,
+  type DevServerFailureType,
+  type WarmActivationOutcome,
+} from "./dev-utils/dev-server-metrics.mjs";
 
 export { TokenManager } from "./dev-utils/token-manager.js";
 
@@ -101,7 +112,12 @@ export {
   type PackageJsonSnapshotReadResult,
 } from "./cli-replacement/package-json-snapshot.mjs";
 
-export { getLogger } from "./telemetry/logging.js";
+export {
+  getErrorMeta,
+  getLogger,
+  type ErrorMeta,
+  type Logger,
+} from "./telemetry/logging.js";
 
 export {
   AuthHotReloadServer,
@@ -111,5 +127,7 @@ export {
 export {
   configureTelemetry,
   deploymentType,
+  getMeter,
+  getTracer,
   isCloudPrem,
 } from "./telemetry/index.js";

package/src/sdk.test.ts

@@ -7,12 +7,23 @@ import {
   type GetPublicOrganizationSummaryResponseBody,
 } from "@superblocksteam/shared";
 
-const { fetchApplicationCommits, fetchAuditEvents, fetchOrganizationSummary } =
-  vi.hoisted(() => ({
-    fetchApplicationCommits: vi.fn(),
-    fetchAuditEvents: vi.fn(),
-    fetchOrganizationSummary: vi.fn(),
-  }));
+import type { PlanSummary } from "./index.js";
+
+const {
+  fetchApplicationCommits,
+  fetchAuditEvents,
+  fetchBillingUsageLimits,
+  fetchOrganizationSummary,
+  updateOrgBillingUsageLimit,
+  updateUserBillingUsageLimit,
+} = vi.hoisted(() => ({
+  fetchApplicationCommits: vi.fn(),
+  fetchAuditEvents: vi.fn(),
+  fetchBillingUsageLimits: vi.fn(),
+  fetchOrganizationSummary: vi.fn(),
+  updateOrgBillingUsageLimit: vi.fn(),
+  updateUserBillingUsageLimit: vi.fn(),
+}));
 
 vi.mock("./client.js", async () => {
   const actual = await vi.importActual("./client.js");
@@ -21,12 +32,55 @@ vi.mock("./client.js", async () => {
     ...actual,
     fetchApplicationCommits,
     fetchAuditEvents,
+    fetchBillingUsageLimits,
     fetchOrganizationSummary,
+    updateOrgBillingUsageLimit,
+    updateUserBillingUsageLimit,
   };
 });
 
 import { SuperblocksSdk } from "./sdk.js";
 
+describe("PlanSummary", () => {
+  it("types enterprise contract limits and usage fields", () => {
+    const plan: PlanSummary = {
+      billingInterval: "annual",
+      builderSeatsAssigned: 12,
+      builderSeatsTotal: 20,
+      contractEnd: "2027-05-01",
+      contractStart: "2026-05-01",
+      contractType: "dollar_commit",
+      creditsPerSeat: null,
+      currentPlanCredits: 0,
+      currentUsageCredits: 0,
+      cycleEnd: "2026-05-31",
+      cycleStart: "2026-05-01",
+      deployedAppCostCents: 2500,
+      deployedAppPriceAnnual: null,
+      deployedAppPriceMonthly: null,
+      deployedAppsAdditional: 0,
+      deployedAppsIncluded: 0,
+      deployedAppsLimit: 0,
+      deployedAppsUsed: 4,
+      dollarCommitAmountCents: 1000000,
+      dollarCommitUsedCents: 250000,
+      overageAppsEnabled: true,
+      overageCreditsEnabled: true,
+      overageSeatsEnabled: false,
+      pricePerSeatAnnual: null,
+      pricePerSeatMonthly: null,
+      seatsUnlimited: false,
+      subscriptionStatus: "active",
+      topupCreditsPurchased: 0,
+      topupCreditsUsed: 0,
+      usageResetPeriodLimit: 0,
+      usageResetPeriodType: "monthly",
+    };
+
+    expect(plan.dollarCommitUsedCents).toBe(250000);
+  });
+});
+
 describe("SuperblocksSdk.fetchOrganizationSummary", () => {
   beforeEach(() => {
     fetchApplicationCommits.mockReset();
@@ -66,6 +120,91 @@ describe("SuperblocksSdk.fetchOrganizationSummary", () => {
   });
 });
 
+describe("SuperblocksSdk billing usage limit methods", () => {
+  beforeEach(() => {
+    fetchBillingUsageLimits.mockReset();
+    updateOrgBillingUsageLimit.mockReset();
+    updateUserBillingUsageLimit.mockReset();
+  });
+
+  it("delegates listing usage limits with the SDK context", async () => {
+    const expectedResponse = {
+      limits: [
+        {
+          id: "limit-1",
+          orgId: "org-1",
+          userId: null,
+          amountLimitCents: null,
+          creditLimit: 5000,
+          updatedAt: "2026-05-01T00:00:00.000Z",
+          updatedBy: "admin-1",
+        },
+      ],
+      orgLimit: null,
+    };
+    fetchBillingUsageLimits.mockResolvedValue(expectedResponse);
+
+    const sdk = new SuperblocksSdk(
+      "test-token",
+      "https://staging.superblocks.com",
+      "1.2.3",
+    );
+
+    await expect(sdk.fetchBillingUsageLimits()).resolves.toEqual(
+      expectedResponse,
+    );
+    expect(fetchBillingUsageLimits).toHaveBeenCalledWith({
+      cliVersion: "1.2.3",
+      token: "test-token",
+      superblocksBaseUrl: "https://staging.superblocks.com",
+    });
+  });
+
+  it("delegates user usage limit updates with the SDK context", async () => {
+    updateUserBillingUsageLimit.mockResolvedValue({ success: true });
+
+    const sdk = new SuperblocksSdk(
+      "test-token",
+      "https://staging.superblocks.com",
+      "1.2.3",
+    );
+
+    await expect(
+      sdk.updateUserBillingUsageLimit({
+        amountLimitCents: 2500,
+        userId: "user-1",
+      }),
+    ).resolves.toEqual({ success: true });
+    expect(updateUserBillingUsageLimit).toHaveBeenCalledWith({
+      cliVersion: "1.2.3",
+      token: "test-token",
+      superblocksBaseUrl: "https://staging.superblocks.com",
+      amountLimitCents: 2500,
+      userId: "user-1",
+    });
+  });
+
+  it("delegates organization usage limit updates with the SDK context", async () => {
+    updateOrgBillingUsageLimit.mockResolvedValue({ success: true });
+
+    const sdk = new SuperblocksSdk(
+      "test-token",
+      "https://staging.superblocks.com",
+      "1.2.3",
+    );
+
+    await expect(
+      sdk.updateOrgBillingUsageLimit({ creditLimit: 5000 }),
+    ).resolves.toEqual({ success: true });
+    expect(updateOrgBillingUsageLimit).toHaveBeenCalledWith({
+      cliVersion: "1.2.3",
+      token: "test-token",
+      superblocksBaseUrl: "https://staging.superblocks.com",
+      creditLimit: 5000,
+    });
+  });
+});
+
 describe("SuperblocksSdk.fetchApplicationCommits", () => {
   beforeEach(() => {
     fetchApplicationCommits.mockReset();

package/src/sdk.ts

@@ -39,6 +39,7 @@ import {
   fetchChatHistory,
   fetchBillingPlanSummary,
   fetchBillingUsageDaily,
+  fetchBillingUsageLimits,
   fetchBillingUsageRecords,
   fetchCurrentUser,
   fetchFact,
@@ -64,6 +65,8 @@ import {
   deployApi,
   fetchApplicationDeployments,
   undeployApplication,
+  updateOrgBillingUsageLimit,
+  updateUserBillingUsageLimit,
 } from "./client.js";
 import type {
   ApplicationGitConfig,
@@ -72,6 +75,7 @@ import type {
   AuditEventsAggregateResponse,
   CreateApplicationResult,
   CreateRbacAssignmentsRequest,
+  BillingUsageLimitsResponse,
   DailyUsageRow,
   FolderMutationPayload,
   FolderSummary,
@@ -84,7 +88,9 @@ import type {
   PushMultiPageApplicationWithCommitConfig,
   SyncRequest,
   SyncResponse,
+  UpdateOrgBillingUsageLimitRequest,
   UpdateRbacAssignmentRequest,
+  UpdateUserBillingUsageLimitRequest,
   UsageRecordRow,
 } from "./client.js";
 import {
@@ -893,6 +899,36 @@ export class SuperblocksSdk {
     });
   }
 
+  async fetchBillingUsageLimits(): Promise<BillingUsageLimitsResponse> {
+    return fetchBillingUsageLimits({
+      cliVersion: this.cliVersion,
+      token: this.token,
+      superblocksBaseUrl: this.superblocksBaseUrl,
+    });
+  }
+
+  async updateUserBillingUsageLimit(
+    input: UpdateUserBillingUsageLimitRequest,
+  ): Promise<{ success: boolean }> {
+    return updateUserBillingUsageLimit({
+      cliVersion: this.cliVersion,
+      token: this.token,
+      superblocksBaseUrl: this.superblocksBaseUrl,
+      ...input,
+    });
+  }
+
+  async updateOrgBillingUsageLimit(
+    input: UpdateOrgBillingUsageLimitRequest,
+  ): Promise<{ success: boolean }> {
+    return updateOrgBillingUsageLimit({
+      cliVersion: this.cliVersion,
+      token: this.token,
+      superblocksBaseUrl: this.superblocksBaseUrl,
+      ...input,
+    });
+  }
+
   async sync({
     applicationId,
     payload,

package/src/telemetry/index.ts

@@ -1,6 +1,6 @@
 import os from "node:os";
 
-import { trace, type Tracer } from "@opentelemetry/api";
+import { metrics, type Meter, trace, type Tracer } from "@opentelemetry/api";
 import { logs, type Logger } from "@opentelemetry/api-logs";
 import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
@@ -230,3 +230,11 @@ export function getTracer(): Tracer {
   // Fallback to global API if telemetry not initialized
   return trace.getTracer(SERVICE_NAME, packageJson.version);
 }
+
+export function getMeter(): Meter {
+  if (isTelemetryInitialized()) {
+    return getTelemetryInstance().getMeter(SERVICE_NAME);
+  }
+  // Fallback to global API if telemetry not initialized
+  return metrics.getMeter(SERVICE_NAME, packageJson.version);
+}

package/src/telemetry/logging.ts

@@ -59,7 +59,7 @@ const winstonLogger = createLogger({
   transports: activeTransports,
 });
 
-interface ErrorMeta {
+export interface ErrorMeta {
   error: {
     kind: string;
     message: string;
@@ -156,7 +156,7 @@ export function getErrorMeta(error: unknown): ErrorMeta {
   return {
     error: {
       kind: "Unknown Error",
-      message: JSON.stringify(error),
+      message: safeStringify(error) ?? String(error),
     },
   };
 }

package/src/telemetry/memory-metrics.ts

@@ -0,0 +1,90 @@
+import {
+  PerformanceObserver,
+  type PerformanceObserverEntryList,
+} from "node:perf_hooks";
+
+import type { BatchObservableResult } from "@opentelemetry/api";
+
+import { getMeter } from "./index.js";
+
+let cleanupFn: (() => void) | undefined;
+
+export function startMemoryMetrics(): void {
+  if (cleanupFn) {
+    return;
+  }
+
+  const meter = getMeter();
+
+  const heapUsedGauge = meter.createObservableGauge(
+    "nodejs.memory.heap_used_bytes",
+    { description: "V8 heap memory used (bytes)", unit: "By" },
+  );
+  const heapTotalGauge = meter.createObservableGauge(
+    "nodejs.memory.heap_total_bytes",
+    { description: "V8 heap memory allocated (bytes)", unit: "By" },
+  );
+  const rssGauge = meter.createObservableGauge("nodejs.memory.rss_bytes", {
+    description: "Resident Set Size - total memory allocated for the process",
+    unit: "By",
+  });
+  const externalGauge = meter.createObservableGauge(
+    "nodejs.memory.external_bytes",
+    {
+      description: "Memory used by C++ objects bound to JavaScript objects",
+      unit: "By",
+    },
+  );
+  const arrayBuffersGauge = meter.createObservableGauge(
+    "nodejs.memory.array_buffers_bytes",
+    {
+      description:
+        "Memory allocated for ArrayBuffers and SharedArrayBuffers (also included in external)",
+      unit: "By",
+    },
+  );
+
+  const gcCountCounter = meter.createCounter("nodejs.gc.count", {
+    description: "Number of garbage collection events",
+    unit: "{event}",
+  });
+
+  const gauges = [
+    heapUsedGauge,
+    heapTotalGauge,
+    rssGauge,
+    externalGauge,
+    arrayBuffersGauge,
+  ];
+
+  // Single memoryUsage() call per export interval for all 5 gauges (idiomatic OTEL batch pattern).
+  const batchCb = (result: BatchObservableResult) => {
+    const mem = process.memoryUsage();
+    result.observe(heapUsedGauge, mem.heapUsed);
+    result.observe(heapTotalGauge, mem.heapTotal);
+    result.observe(rssGauge, mem.rss);
+    result.observe(externalGauge, mem.external);
+    result.observe(arrayBuffersGauge, mem.arrayBuffers);
+  };
+
+  meter.addBatchObservableCallback(batchCb, gauges);
+
+  const gcObserver = new PerformanceObserver(
+    (list: PerformanceObserverEntryList) => {
+      gcCountCounter.add(list.getEntries().length);
+    },
+  );
+  gcObserver.observe({ entryTypes: ["gc"], buffered: false });
+
+  cleanupFn = () => {
+    gcObserver.disconnect();
+    meter.removeBatchObservableCallback(batchCb, gauges);
+  };
+}
+
+export function stopMemoryMetrics(): void {
+  if (cleanupFn) {
+    cleanupFn();
+    cleanupFn = undefined;
+  }
+}

package/src/types/common.ts

@@ -12,12 +12,12 @@ export interface UserMeDto {
 export interface FlagBootstrap {
   "ui.enable-resource-signing"?: boolean;
   "superblocks.git.split.large.steps.enabled"?: boolean;
-  "superblocks.git.split.large.steps.new.enabled"?: boolean;
   "superblocks.git.split.large.step.lines"?: number;
   "ui.code-mode.enable-session-recording"?: boolean;
   "superblocks.dev-server.inactivity-timeout.cloud"?: number;
   "superblocks.dev-server.inactivity-timeout.local"?: number;
   "superblocks.dev-server.llmobs.enabled"?: boolean;
+  "superblocks.dev-server.memory-metrics.enabled"?: boolean;
   "superblocks.deploy.include-dot-superblocks"?: boolean;
 }
 

package/src/version-control.mts

@@ -1,11 +1,11 @@
-import * as https from "https";
+import * as https from "node:https";
 import path from "node:path";
 import { dirname } from "path";
 
 import { bold } from "colorette";
 import fs from "fs-extra";
 import { isEmpty, isArray, isObject, get } from "lodash-es";
-import * as semver from "semver";
+import semver from "semver";
 import { simpleGit } from "simple-git";
 import type { SimpleGit, StatusResult } from "simple-git";
 import slugify from "slugify";
@@ -419,10 +419,7 @@ export async function writeResourceToDisk(
         configType: "APPLICATION",
         defaultPageId: resource.page?.id,
         id: resource.application.id,
-        metadata: getResourceConfigMetadata(
-          featureFlags,
-          existingApplicationConfig,
-        ),
+        metadata: getResourceConfigMetadata(existingApplicationConfig),
       };
 
       const apiRepresentation =
@@ -506,10 +503,7 @@ export async function writeResourceToDisk(
       const backendConfig: SuperblocksBackendConfig = {
         id: resourceId,
         configType: "BACKEND",
-        metadata: getResourceConfigMetadata(
-          featureFlags,
-          existingBackendConfig,
-        ),
+        metadata: getResourceConfigMetadata(existingBackendConfig),
       };
 
       const apiRepresentation =
@@ -594,7 +588,6 @@ export async function writeApplicationToDisk({
       appDirName,
       directoryContentsHash,
       branch,
-      featureFlags,
     );
     return {
       location: relativeLocation,
@@ -636,10 +629,7 @@ async function writeV1ApplicationToDisk(
   const newApplicationConfig: SuperblocksApplicationConfig = {
     configType: "APPLICATION",
     id: resource.application.id,
-    metadata: getResourceConfigMetadata(
-      featureFlags,
-      existingApplicationConfig,
-    ),
+    metadata: getResourceConfigMetadata(existingApplicationConfig),
   };
 
   const apiRepresentation =
@@ -785,7 +775,6 @@ async function writeCodeModeApplicationToDisk(
   appDirName: string,
   directoryContentsHash: string | undefined,
   branch: string | undefined,
-  featureFlags: FeatureFlags,
 ): Promise<void> {
   // Find the existing application config and existing file paths
   const existingApplicationConfig =
@@ -794,10 +783,7 @@ async function writeCodeModeApplicationToDisk(
   const newApplicationConfig: SuperblocksApplicationV2Config = {
     configType: "APPLICATION_V2",
     id: resource.application.id,
-    metadata: getResourceConfigMetadata(
-      featureFlags,
-      existingApplicationConfig,
-    ),
+    metadata: getResourceConfigMetadata(existingApplicationConfig),
   };
 
   await fs.ensureDir(`${appDirName}/${SUPERBLOCKS_HOME_FOLDER_NAME}`);
@@ -930,20 +916,15 @@ export function addExistingFilePathsForApi(
 }
 
 function getResourceConfigMetadata(
-  featureFlags: FeatureFlags,
   existingResourceConfig: SuperblocksResourceConfig | undefined,
 ): SuperblocksResourceConfigMetadata | undefined {
   if (!existingResourceConfig) {
-    // This is a new application, and we may need to add a metadata field to the application config
-    if (featureFlags.splitLargeApiStepsInNewEnabled()) {
-      return {
-        fileVersion: LATEST_FILE_VERSION,
-      };
-    }
-  } else if (existingResourceConfig.metadata) {
-    return existingResourceConfig.metadata;
+    // This is a new application; tag the application config with the latest file version.
+    return {
+      fileVersion: LATEST_FILE_VERSION,
+    };
   }
-  return undefined;
+  return existingResourceConfig.metadata;
 }
 
 export async function removeResourceFromDisk(

package/test/version-control.test.mts

@@ -662,7 +662,6 @@ describe("version-control", () => {
   describe("writeResourcesToDisk", () => {
     const mockFeatureFlags = new FeatureFlags({
       "superblocks.git.split.large.steps.enabled": true,
-      "superblocks.git.split.large.steps.new.enabled": true,
       "superblocks.git.split.large.step.lines": 10,
     });
 
@@ -931,7 +930,6 @@ describe("version-control", () => {
   describe("writeApplicationToDIsk", () => {
     const mockFeatureFlags = new FeatureFlags({
       "superblocks.git.split.large.steps.enabled": true,
-      "superblocks.git.split.large.steps.new.enabled": false,
       "superblocks.git.split.large.step.lines": 10,
     });