@superblocksteam/sdk 2.0.102 → 2.0.103

package/src/client.ts

@@ -1,11 +1,24 @@
 import * as fs from "node:fs";
 import path from "node:path";
+
+import axios, { AxiosError } from "axios";
+import type { AxiosRequestConfig } from "axios";
+import FormData from "form-data";
+import { isEqual, isEmpty } from "lodash-es";
+
 import { Bucketeer, FileDescriptor } from "@superblocksteam/bucketeer-sdk";
 import {
   CommitType,
   ExportViewMode,
+  type AssignmentDto,
+  type OCSFAuditEvent,
+  type AuditLogDto,
+  type AuditLogEntity,
+  type FactDto,
+  type FactListQuery,
   type GetApplicationCommitsResponseBody,
   type GetPublicOrganizationSummaryResponseBody,
+  type IHomepageApplicationV2Dto,
 } from "@superblocksteam/shared";
 import {
   COMPONENT_EVENT_HEADER,
@@ -18,9 +31,12 @@ import {
   unreachable,
   getSuperblocksDevEnvironmentConfigJson,
 } from "@superblocksteam/util";
-import axios, { AxiosError } from "axios";
-import FormData from "form-data";
-import { isEqual, isEmpty } from "lodash-es";
+import type {
+  LocalGitRepoState,
+  SuperblocksResourceType,
+  ValidateGitSetupRequestBody,
+} from "@superblocksteam/util";
+
 import { doUploadLocalDirectory } from "./dbfs/local.js";
 import {
   BranchNotCheckedOutError,
@@ -29,14 +45,8 @@ import {
 } from "./errors.js";
 import { signingEnabled } from "./flag.js";
 import { connectToISocketRPCServer } from "./socket/index.js";
-import { AgentType } from "./types/index.js";
-import { getAgentUrl } from "./utils.js";
-import {
-  DEFAULT_BRANCH,
-  findGitRepositoryRoot,
-  getCurrentGitBranchIfGit,
-} from "./version-control.mjs";
 import type { StdISocketRPCClient } from "./socket/index.js";
+import { AgentType } from "./types/index.js";
 import type {
   ApiWithPb,
   Page,
@@ -44,15 +54,15 @@ import type {
   DeploymentDto,
   UserMeDto,
 } from "./types/index.js";
-
-import type {
-  LocalGitRepoState,
-  SuperblocksResourceType,
-  ValidateGitSetupRequestBody,
-} from "@superblocksteam/util";
-import type { AxiosRequestConfig } from "axios";
+import { getAgentUrl } from "./utils.js";
+import {
+  DEFAULT_BRANCH,
+  findGitRepositoryRoot,
+  getCurrentGitBranchIfGit,
+} from "./version-control.mjs";
 
 const BASE_BUCKETEER_URL = "api";
+const BASE_SERVER_API_URL_V1 = "api/v1";
 const BASE_SERVER_PUBLIC_API_URL_V1 = "api/v1/public";
 const BASE_SERVER_PUBLIC_API_URL_v2 = "api/v2/public";
 const BASE_SERVER_API_URL_V2 = "api/v2";
@@ -517,7 +527,7 @@ export async function fetchApplications(
   token: string,
   superblocksBaseUrl: string,
   injectedHeaders: Record<string, string> = {},
-) {
+): Promise<IHomepageApplicationV2Dto[]> {
   try {
     const config: AxiosRequestConfig = {
       method: "get",
@@ -532,7 +542,7 @@ export async function fetchApplications(
       },
     };
     const response = await axios(config);
-    return response.data.data.applications;
+    return response.data.data.applications as IHomepageApplicationV2Dto[];
   } catch (e: any) {
     let message: string;
     if (e instanceof AxiosError) {
@@ -986,6 +996,79 @@ export async function fetchOrganizationSummary(
   }
 }
 
+export interface CreateApplicationParams {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  name: string;
+  organizationId: string;
+  codeMode?: boolean;
+  templateName?: string;
+  folderId?: string;
+}
+
+export interface CreateApplicationResult {
+  id: string;
+  name: string;
+  organizationId: string;
+  devEnvEnabled?: boolean;
+}
+
+export async function createApplication({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  name,
+  organizationId,
+  codeMode = true,
+  templateName,
+  folderId,
+}: CreateApplicationParams): Promise<CreateApplicationResult> {
+  const body: Record<string, unknown> = {
+    name,
+    organizationId,
+  };
+  if (codeMode) {
+    body.createUsingReact = true;
+    if (templateName) {
+      body.templateName = templateName;
+    }
+  }
+  if (folderId) {
+    body.folderId = folderId;
+  }
+
+  try {
+    const config: AxiosRequestConfig = {
+      method: "post",
+      url: new URL(
+        `${BASE_SERVER_API_URL_V2}/applications/`,
+        superblocksBaseUrl,
+      ).toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        "Content-Type": "application/json",
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+      data: body,
+    };
+    const response = await axios(config);
+    return response.data.data as CreateApplicationResult;
+  } 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 create application: ${message}`);
+  }
+}
+
 const createSocketConnectionIfNeeded = async (
   cliVersion: string,
   token: string,
@@ -1514,9 +1597,9 @@ export async function fetchApiCommits({
     return serverResponse?.data?.data;
   } catch (e) {
     if (axios.isAxiosError(e) && e.response?.status === 404) {
-      throw new NotFoundError(`Application ${applicationId} was not found`);
+      throw new NotFoundError(`API ${applicationId} was not found`);
     }
-    throw new Error("Could not fetch application");
+    throw new Error("Could not fetch API commits");
   }
 }
 
@@ -1630,6 +1713,1106 @@ export async function uploadApplication({
   await bucketeer.uploadApplication(fds);
 }
 
+export async function fetchRbacAssignments({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  resourceType,
+  resourceId,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  resourceType: string;
+  resourceId: string;
+}): Promise<AssignmentDto[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V2}/rbac/assignments`,
+      superblocksBaseUrl,
+    );
+    url.searchParams.set("resourceType", resourceType);
+    url.searchParams.set("resourceId", resourceId);
+
+    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 AssignmentDto[];
+  } 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 RBAC assignments: ${message}`);
+  }
+}
+
+export interface CreateRbacAssignmentsRequest {
+  assignments: Array<{
+    assignmentType: string;
+    assignmentId: string;
+    resourceType: string;
+    resourceId: string;
+    principalType: string;
+    principalId: string;
+    organizationId: string;
+  }>;
+}
+
+export interface UpdateRbacAssignmentRequest {
+  assignmentType: string;
+  assignmentId: string;
+}
+
+export async function createRbacAssignments({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  payload,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  payload: CreateRbacAssignmentsRequest;
+}): Promise<AssignmentDto[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V2}/rbac/assignments`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "post",
+      url: url.toString(),
+      data: payload,
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as AssignmentDto[];
+  } 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 create RBAC assignments: ${message}`);
+  }
+}
+
+export async function updateRbacAssignment({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  assignmentRecordId,
+  payload,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  assignmentRecordId: string;
+  payload: UpdateRbacAssignmentRequest;
+}): Promise<AssignmentDto> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V2}/rbac/assignments/${assignmentRecordId}`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "put",
+      url: url.toString(),
+      data: payload,
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as AssignmentDto;
+  } 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 RBAC assignment: ${message}`);
+  }
+}
+
+export async function deleteRbacAssignment({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  assignmentRecordId,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  assignmentRecordId: string;
+}): Promise<AssignmentDto> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V2}/rbac/assignments/${assignmentRecordId}`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "delete",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as AssignmentDto;
+  } 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 delete RBAC assignment: ${message}`);
+  }
+}
+
+export interface AuditLogFilters {
+  startTime: string;
+  endTime: string;
+  entityType?: number;
+  auditEntityId?: string;
+  auditEntityType?: number;
+  status?: string;
+  deployed?: boolean;
+  triggeredBy?: string[];
+}
+
+export async function fetchAuditLogs({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  filters,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  filters: AuditLogFilters;
+}): Promise<AuditLogDto[]> {
+  try {
+    const url = new URL(`${BASE_SERVER_API_URL_V2}/audit`, superblocksBaseUrl);
+    url.searchParams.set("startTime", filters.startTime);
+    url.searchParams.set("endTime", filters.endTime);
+    if (filters.entityType !== undefined) {
+      url.searchParams.set("entity_type", String(filters.entityType));
+    }
+    if (filters.auditEntityId !== undefined) {
+      url.searchParams.set("audit_entity_id", filters.auditEntityId);
+    }
+    if (filters.auditEntityType !== undefined) {
+      url.searchParams.set(
+        "audit_entity_type",
+        String(filters.auditEntityType),
+      );
+    }
+    if (filters.status !== undefined) {
+      url.searchParams.set("status", filters.status);
+    }
+    if (filters.deployed !== undefined) {
+      url.searchParams.set("deployed", String(filters.deployed));
+    }
+    if (filters.triggeredBy?.length) {
+      for (const src of filters.triggeredBy) {
+        url.searchParams.append("triggered_by", src);
+      }
+    }
+
+    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 AuditLogDto[];
+  } 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 audit logs: ${message}`);
+  }
+}
+
+export interface AuditEventFilters {
+  timeStart: string;
+  timeEnd: string;
+  classUid?: number;
+  status?: number;
+  severity?: number;
+  actor?: string;
+  resourceType?: string;
+  resourceId?: string;
+  search?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface AuditEventsResponse {
+  events: OCSFAuditEvent[];
+  next_cursor: string | null;
+}
+
+export async function fetchAuditEvents({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  filters,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  filters: AuditEventFilters;
+}): Promise<AuditEventsResponse> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V2}/audit/events`,
+      superblocksBaseUrl,
+    );
+    url.searchParams.set("time_start", filters.timeStart);
+    url.searchParams.set("time_end", filters.timeEnd);
+    if (filters.classUid !== undefined) {
+      url.searchParams.set("class_uid", String(filters.classUid));
+    }
+    if (filters.status !== undefined) {
+      url.searchParams.set("status", String(filters.status));
+    }
+    if (filters.severity !== undefined) {
+      url.searchParams.set("severity", String(filters.severity));
+    }
+    if (filters.actor !== undefined) {
+      url.searchParams.set("actor", filters.actor);
+    }
+    if (filters.resourceType !== undefined) {
+      url.searchParams.set("resource_type", filters.resourceType);
+    }
+    if (filters.resourceId !== undefined) {
+      url.searchParams.set("resource_id", filters.resourceId);
+    }
+    if (filters.search !== undefined) {
+      url.searchParams.set("search", filters.search);
+    }
+    if (filters.cursor !== undefined) {
+      url.searchParams.set("cursor", filters.cursor);
+    }
+    if (filters.limit !== undefined) {
+      url.searchParams.set("limit", String(filters.limit));
+    }
+
+    const config: AxiosRequestConfig = {
+      method: "get",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    const responseData = response.data as
+      | AuditEventsResponse
+      | { data?: AuditEventsResponse };
+    if (
+      responseData &&
+      typeof responseData === "object" &&
+      "data" in responseData &&
+      responseData.data !== undefined
+    ) {
+      return responseData.data;
+    }
+    return responseData as AuditEventsResponse;
+  } 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 audit events: ${message}`);
+  }
+}
+
+export interface IntegrationFilters {
+  kind?: string[];
+  slug?: string[];
+}
+
+export interface IntegrationSummary {
+  id: string;
+  name: string;
+  pluginId: string;
+  organizationId: string;
+  kind: string;
+  slug?: string;
+  created: string;
+  updated: string;
+}
+
+export interface IntegrationDetail extends IntegrationSummary {
+  configurations?: unknown[];
+  demoIntegrationId?: string;
+  enabledForV2?: boolean;
+  isUserConfigured?: boolean;
+  ownerEmail?: string;
+}
+
+export interface IntegrationMutationPayload {
+  [key: string]: unknown;
+}
+
+export async function fetchIntegrations({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  filters,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  filters?: IntegrationFilters;
+}): Promise<IntegrationSummary[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/integrations`,
+      superblocksBaseUrl,
+    );
+    if (filters?.kind) {
+      for (const k of filters.kind) {
+        url.searchParams.append("kind", k);
+      }
+    }
+    if (filters?.slug) {
+      for (const s of filters.slug) {
+        url.searchParams.append("slug", s);
+      }
+    }
+
+    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 IntegrationSummary[];
+  } 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 integrations: ${message}`);
+  }
+}
+
+export async function fetchIntegrationById({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  integrationId,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  integrationId: string;
+}): Promise<IntegrationDetail> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/integrations/${integrationId}`,
+      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 IntegrationDetail;
+  } 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 integration: ${message}`);
+  }
+}
+
+export async function createIntegration({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  payload,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  payload: IntegrationMutationPayload;
+}): Promise<IntegrationDetail> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/integrations`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "post",
+      url: url.toString(),
+      data: payload,
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as IntegrationDetail;
+  } 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 create integration: ${message}`);
+  }
+}
+
+export async function updateIntegration({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  integrationId,
+  payload,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  integrationId: string;
+  payload: IntegrationMutationPayload;
+}): Promise<IntegrationDetail> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/integrations/${integrationId}`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "put",
+      url: url.toString(),
+      data: payload,
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as IntegrationDetail;
+  } 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 integration: ${message}`);
+  }
+}
+
+export async function deleteIntegration({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  integrationId,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  integrationId: string;
+}): Promise<IntegrationDetail> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/integrations/${integrationId}`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "delete",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as IntegrationDetail;
+  } 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 delete integration: ${message}`);
+  }
+}
+
+export interface FolderSummary {
+  id: string;
+  name: string;
+  organizationId: string;
+  totalResources?: number;
+  updated?: string;
+}
+
+export interface FolderMutationPayload {
+  name: string;
+}
+
+export async function fetchFolders({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+}): Promise<FolderSummary[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/folders`,
+      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 FolderSummary[];
+  } 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 folders: ${message}`);
+  }
+}
+
+export async function createFolder({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  payload,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  payload: FolderMutationPayload;
+}): Promise<FolderSummary> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/folders`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "post",
+      url: url.toString(),
+      data: { folder: payload },
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as FolderSummary;
+  } 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 create folder: ${message}`);
+  }
+}
+
+export async function updateFolder({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  folderId,
+  payload,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  folderId: string;
+  payload: FolderMutationPayload;
+}): Promise<FolderSummary> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/folders/${folderId}`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "put",
+      url: url.toString(),
+      data: { folder: payload },
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as FolderSummary;
+  } 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 folder: ${message}`);
+  }
+}
+
+export async function deleteFolder({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  folderId,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  folderId: string;
+}): Promise<FolderSummary> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/folders/${folderId}`,
+      superblocksBaseUrl,
+    );
+    const config: AxiosRequestConfig = {
+      method: "delete",
+      url: url.toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as FolderSummary;
+  } 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 delete folder: ${message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Billing
+// ---------------------------------------------------------------------------
+
+export interface DailyUsageRow {
+  date: string;
+  creditsUsed: number;
+}
+
+export interface UsageRecordRow {
+  date: string;
+  email: string;
+  name: string;
+  creditsUsed: number;
+  source: string;
+}
+
+export interface PlanSummary {
+  billingInterval: "annual" | "monthly";
+  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;
+}
+
+export async function fetchBillingUsageDaily({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  startDate,
+  endDate,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  startDate: string;
+  endDate: string;
+}): Promise<DailyUsageRow[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/billing/usage-daily`,
+      superblocksBaseUrl,
+    );
+    url.searchParams.set("start", startDate);
+    url.searchParams.set("end", endDate);
+
+    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.dailyUsage as DailyUsageRow[];
+  } 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 daily usage: ${message}`);
+  }
+}
+
+export async function fetchBillingUsageRecords({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  startDate,
+  endDate,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  startDate: string;
+  endDate: string;
+}): Promise<UsageRecordRow[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/billing/usage-records`,
+      superblocksBaseUrl,
+    );
+    url.searchParams.set("start", startDate);
+    url.searchParams.set("end", endDate);
+
+    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.rows as UsageRecordRow[];
+  } 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 records: ${message}`);
+  }
+}
+
+export async function fetchBillingPlanSummary({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+}): Promise<PlanSummary> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/billing/plan-summary`,
+      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 PlanSummary;
+  } 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 plan summary: ${message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Knowledge (Facts)
+// ---------------------------------------------------------------------------
+
+export async function fetchFacts({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  query,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  query?: FactListQuery;
+}): Promise<FactDto[]> {
+  try {
+    const url = new URL(`${BASE_SERVER_API_URL_V1}/facts`, superblocksBaseUrl);
+    if (query?.entityScope)
+      url.searchParams.set("entityScope", query.entityScope);
+    if (query?.entityId) url.searchParams.set("entityId", query.entityId);
+    if (query?.accessType) url.searchParams.set("accessType", query.accessType);
+    if (query?.isEnabled !== undefined)
+      url.searchParams.set("isEnabled", String(query.isEnabled));
+    if (query?.search) url.searchParams.set("search", query.search);
+    if (query?.limit !== undefined)
+      url.searchParams.set("limit", String(query.limit));
+    if (query?.offset !== undefined)
+      url.searchParams.set("offset", String(query.offset));
+    if (query?.sortBy) url.searchParams.set("sortBy", query.sortBy);
+    if (query?.sortOrder) url.searchParams.set("sortOrder", query.sortOrder);
+
+    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.facts as FactDto[];
+  } 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 knowledge entries: ${message}`);
+  }
+}
+
+export async function fetchFact({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+  factId,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+  factId: string;
+}): Promise<FactDto> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V1}/facts/${encodeURIComponent(factId)}`,
+      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 FactDto;
+  } 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 knowledge entry: ${message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Audit entities
+// ---------------------------------------------------------------------------
+
+export async function fetchAuditEntities({
+  cliVersion,
+  token,
+  superblocksBaseUrl,
+}: {
+  cliVersion: string;
+  token: string;
+  superblocksBaseUrl: string;
+}): Promise<AuditLogEntity[]> {
+  try {
+    const url = new URL(
+      `${BASE_SERVER_API_URL_V2}/audit/entities`,
+      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 AuditLogEntity[];
+  } 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 audit entities: ${message}`);
+  }
+}
+
 function filesToFileDescriptors(files: string[], appRoot?: string) {
   const fds = files.map((file) => {
     const relativePath = appRoot ? path.relative(appRoot, file) : undefined;