@supernova-studio/client 1.96.6 → 1.96.7

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@supernova-studio/client",
-  "version": "1.96.6",
+  "version": "1.96.7",
   "description": "Supernova Data Models",
   "source": "src/index.ts",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -13,33 +13,44 @@
       },
       "require": {
         "types": "./dist/index.d.ts",
-        "module": "./dist/index.mjs",
         "default": "./dist/index.js"
       }
     }
   },
   "files": [
-    "dist/**"
+    "dist/**",
+    "src/**"
   ],
   "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
+    "build": "npm run index && tsc -b && tsup",
+    "emit-types": "tsc -b",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
     "test:unit": "vitest run",
     "index": "node ./create-indexes.js"
   },
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@supernova-studio/model": "1.96.7",
     "p-queue": "^8.0.1",
+    "prosemirror-model": "^1.25.4",
     "queue-promise": "^2.2.1",
     "y-prosemirror": "^1.3.7",
+    "y-protocols": "^1.0.7",
     "y-utility": "0.1.4",
-    "prosemirror-model": "^1.25.4",
     "yjs": "^13.6.29",
     "zod": "3.25.76"
   },
   "devDependencies": {
+    "date-fns": "2.30.0",
     "tsup": "8.5.0",
-    "typescript": "5.8.3"
+    "typescript": "5.8.3",
+    "vite-tsconfig-paths": "4.3.2",
+    "vitest": "4.1.4"
+  },
+  "module": "./dist/index.mjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Supernova-Studio/cloud.git"
   }
 }

package/src/api/client.ts

@@ -0,0 +1,62 @@
+import {
+  AuthTokensEndpoint,
+  CodegenEndpoint,
+  FeedbackEndpoint,
+  FilesEndpoint,
+  StorybookSitesEndpoint,
+  WorkspacesEndpoint,
+} from "./endpoints";
+import { DesignSystemsEndpoint } from "./endpoints/design-system";
+import { ForgeEndpoint } from "./endpoints/forge";
+import { LiveblocksEndpoint } from "./endpoints/liveblocks";
+import { MCPStreamsEndpoint } from "./endpoints/mcp";
+import { SandboxesEndpoint } from "./endpoints/sandboxes";
+import { ThreadsEndpoint } from "./endpoints/threads";
+import { UsersEndpoint } from "./endpoints/users";
+import { RequestExecutor } from "./transport/request-executor";
+
+type SupernovaApiClientConfig = {
+  baseUrl: string;
+  accessToken: string;
+  apiSecret?: string;
+};
+
+export class SupernovaApiClient {
+  readonly authTokens: AuthTokensEndpoint;
+  readonly users: UsersEndpoint;
+  readonly workspaces: WorkspacesEndpoint;
+  readonly designSystems: DesignSystemsEndpoint;
+  readonly codegen: CodegenEndpoint;
+  readonly liveblocks: LiveblocksEndpoint;
+  readonly feedback: FeedbackEndpoint;
+  readonly forge: ForgeEndpoint;
+  readonly files: FilesEndpoint;
+  readonly threads: ThreadsEndpoint;
+  readonly mcpStreams: MCPStreamsEndpoint;
+  readonly sandboxes: SandboxesEndpoint;
+  readonly storybookSites: StorybookSitesEndpoint;
+
+  constructor(readonly config: SupernovaApiClientConfig) {
+    const apiSecret = config.apiSecret ?? process?.env?.SUPERNOVA_API_SECRET;
+
+    const requestExecutor = new RequestExecutor({
+      apiSecret,
+      baseUrl: config.baseUrl,
+      accessToken: config.accessToken,
+    });
+
+    this.authTokens = new AuthTokensEndpoint(requestExecutor);
+    this.users = new UsersEndpoint(requestExecutor);
+    this.workspaces = new WorkspacesEndpoint(requestExecutor);
+    this.designSystems = new DesignSystemsEndpoint(requestExecutor);
+    this.codegen = new CodegenEndpoint(requestExecutor);
+    this.liveblocks = new LiveblocksEndpoint(requestExecutor);
+    this.feedback = new FeedbackEndpoint(requestExecutor);
+    this.forge = new ForgeEndpoint(requestExecutor);
+    this.files = new FilesEndpoint(requestExecutor);
+    this.threads = new ThreadsEndpoint(requestExecutor);
+    this.mcpStreams = new MCPStreamsEndpoint(requestExecutor);
+    this.sandboxes = new SandboxesEndpoint(requestExecutor);
+    this.storybookSites = new StorybookSitesEndpoint(requestExecutor);
+  }
+}

package/src/api/conversion/analytics/index.ts

@@ -0,0 +1,3 @@
+export * from "./page-visits-to-comparison-dto";
+export * from "./page-visits-to-dto";
+export * from "./page-visits-to-heatmap-dto";

package/src/api/conversion/analytics/page-visits-to-comparison-dto.ts

@@ -0,0 +1,65 @@
+import { PublishedDocPageVisitsEntry, SupernovaException } from "@supernova-studio/model";
+import {
+  DTODocumentationAnalyticsTimeFrame,
+  DTOPublishedDocAnalyticsComparisonData,
+  DTOPublishedDocPageAnalyticsComparisonData,
+} from "../../dto";
+import { documentationAnalyticsToGlobalDto } from "./page-visits-to-dto";
+
+//
+// Page analytics
+//
+
+type PageAnalyticsInput = {
+  pagePersistentId: string;
+  priorDataPoints: PublishedDocPageVisitsEntry[];
+  currentDataPoints: PublishedDocPageVisitsEntry[];
+  timeFrame: DTODocumentationAnalyticsTimeFrame;
+};
+
+export function documentationAnalyticsToPageComparisonDto(
+  input: PageAnalyticsInput
+): DTOPublishedDocPageAnalyticsComparisonData {
+  const { pagePersistentId } = input;
+
+  function validateDataPoint(dataPoint: PublishedDocPageVisitsEntry) {
+    if (dataPoint.pagePersistentId !== pagePersistentId) {
+      throw SupernovaException.shouldNotHappen(`Tried to include invalid analytics data point!`);
+    }
+  }
+
+  input.priorDataPoints.forEach(validateDataPoint);
+  input.currentDataPoints.forEach(validateDataPoint);
+
+  return {
+    ...documentationAnalyticsToComparisonDto(input),
+    pagePersistentId,
+  };
+}
+
+//
+// Global analytics
+//
+
+type GlobalAnalyticsInput = {
+  priorDataPoints: PublishedDocPageVisitsEntry[];
+  currentDataPoints: PublishedDocPageVisitsEntry[];
+  timeFrame: DTODocumentationAnalyticsTimeFrame;
+};
+
+export function documentationAnalyticsToComparisonDto(
+  input: GlobalAnalyticsInput
+): DTOPublishedDocAnalyticsComparisonData {
+  const { timeFrame } = input;
+
+  const priorDataPoints = documentationAnalyticsToGlobalDto(input.priorDataPoints);
+  const currentDataPoints = documentationAnalyticsToGlobalDto(input.currentDataPoints);
+
+  return {
+    timeFrame,
+    priorSessionCount: priorDataPoints.reduce((sum, d) => sum + d.sessions, 0),
+    priorVisitCount: priorDataPoints.reduce((sum, d) => sum + d.visits, 0),
+    currentSessionCount: currentDataPoints.reduce((sum, d) => sum + d.sessions, 0),
+    currentVisitCount: currentDataPoints.reduce((sum, d) => sum + d.visits, 0),
+  };
+}

package/src/api/conversion/analytics/page-visits-to-dto.ts

@@ -0,0 +1,68 @@
+import { groupBy, nonNullishFilter, PublishedDocPageVisitsEntry } from "@supernova-studio/model";
+import { DTOPublishedDocPageVisitData, DTOPublishedDocVisitData } from "../../dto";
+
+//
+// Analytics data conversion
+//
+
+export function documentationAnalyticsToGlobalDto(entries: PublishedDocPageVisitsEntry[]): DTOPublishedDocVisitData[] {
+  return squashAndConvertToDto(entries);
+}
+
+//
+// Analytics data per page conversion
+//
+
+export function documentationAnalyticsToPageDto(
+  entries: PublishedDocPageVisitsEntry[]
+): DTOPublishedDocPageVisitData[] {
+  // Group by page id
+  const byPageIdEntries = Array.from(groupBy(entries, e => e.pagePersistentId).entries());
+  byPageIdEntries.sort((lhs, rhs) => lhs[0].localeCompare(rhs[0]));
+
+  return byPageIdEntries.flatMap(([pagePersistentId, entries]) => {
+    const dtoWithoutPageId = squashAndConvertToDto(entries);
+    return dtoWithoutPageId.map(dto => ({ ...dto, pagePersistentId }));
+  });
+}
+
+//
+// Base
+//
+
+function squashAndConvertToDto(entries: PublishedDocPageVisitsEntry[]): DTOPublishedDocVisitData[] {
+  // Group by beginning of day
+  const byDay = groupBy(entries, e => getStartOfUTCDay(e.timestamp));
+
+  const obj = Object.fromEntries(
+    Array.from(byDay.entries()).map(([date, values]) => [new Date(date).toISOString(), values.length])
+  );
+
+  // Convert model to DTO by squashing model entries that belong to the same day
+  return Array.from(byDay.entries()).map(([startOfDay, dayEntries]) => {
+    const firstEntry = dayEntries[0];
+
+    // Sessions are number of unique user IDs who visited the page during that day
+    const uniqueSessions = new Set(dayEntries.map(e => e.anonymousId).filter(nonNullishFilter)).size;
+
+    // Visits are sum of all recorded visits of the page during that day
+    const visitsSum = dayEntries.reduce((prev, curr) => prev + curr.visits, 0);
+
+    return {
+      versionId: firstEntry.versionId,
+      timestamp: new Date(startOfDay),
+      sessions: uniqueSessions,
+      visits: visitsSum,
+
+      ...(firstEntry.locale && { locale: firstEntry.locale }),
+    };
+  });
+}
+
+function getStartOfUTCDay(date: Date): number {
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth();
+  const day = date.getUTCDate();
+
+  return Date.UTC(year, month, day, 0, 0, 0, 0);
+}

package/src/api/conversion/analytics/page-visits-to-heatmap-dto.ts

@@ -0,0 +1,49 @@
+import { groupBy, PublishedDocPageVisitsEntry } from "@supernova-studio/model";
+import { DTODocumentationAnalyticsTimeFrame, DTOPublishedDocVisitHeatMapWeek } from "../../dto";
+
+export function documentationAnalyticsToHeatMapDto(
+  entries: PublishedDocPageVisitsEntry[],
+  timeFrame: DTODocumentationAnalyticsTimeFrame
+): DTOPublishedDocVisitHeatMapWeek {
+  const byWeekDay = groupBy(entries, e => e.timestamp.getUTCDay());
+
+  return {
+    timeFrame,
+    mon: entriesToHeatmapDay(byWeekDay.get(1)),
+    tue: entriesToHeatmapDay(byWeekDay.get(2)),
+    wed: entriesToHeatmapDay(byWeekDay.get(3)),
+    thu: entriesToHeatmapDay(byWeekDay.get(4)),
+    fri: entriesToHeatmapDay(byWeekDay.get(5)),
+    sat: entriesToHeatmapDay(byWeekDay.get(6)),
+    sun: entriesToHeatmapDay(byWeekDay.get(7)),
+  };
+}
+
+function entriesToHeatmapDay(entries: PublishedDocPageVisitsEntry[] | undefined): number[] {
+  const byHour = groupBy(entries ?? [], e => e.timestamp.getUTCHours());
+
+  return [
+    sumVisits(byHour.get(0), byHour.get(1)), // 0am-2am
+    sumVisits(byHour.get(2), byHour.get(3)), // 2am-4am
+    sumVisits(byHour.get(4), byHour.get(5)), // 4am-6am
+    sumVisits(byHour.get(6), byHour.get(7)), // 6am-6am
+    sumVisits(byHour.get(8), byHour.get(9)), // 8am-6am
+    sumVisits(byHour.get(10), byHour.get(11)), // 10am-12pm
+    sumVisits(byHour.get(12), byHour.get(13)), // 12pm-2pm
+    sumVisits(byHour.get(14), byHour.get(15)), // 2pm-4pm
+    sumVisits(byHour.get(16), byHour.get(17)), // 4pm-6pm
+    sumVisits(byHour.get(18), byHour.get(19)), // 6pm-8pm
+    sumVisits(byHour.get(20), byHour.get(21)), // 8pm-10pm
+    sumVisits(byHour.get(22), byHour.get(23)), // 10pm-12pm
+  ];
+}
+
+function sumVisits(...entryArrays: (PublishedDocPageVisitsEntry[] | undefined)[]) {
+  let sum = 0;
+
+  entryArrays.forEach(a => {
+    a?.forEach(e => (sum += e.visits));
+  });
+
+  return sum;
+}

package/src/api/conversion/documentation/documentation-group-v1-to-dto.ts

@@ -0,0 +1,114 @@
+import {
+  DocumentationGroupV1,
+  DocumentationItemConfigurationV1,
+  DocumentationPageV1,
+  DocumentationPageV2,
+  groupBy,
+} from "@supernova-studio/model";
+import { DTODocumentationGroupStructureV1, DTODocumentationGroupV1 } from "../../dto/elements/documentation/group-v1";
+import {
+  documentationItemConfigurationToDTOV1,
+  getDtoDefaultItemConfigurationV1,
+} from "./documentation-item-configuration-v1-to-dto";
+import { applyPrivacyConfigurationToNestedItems } from "./documentation-page-to-dto-utils";
+
+// The fact that DTO conversion is located here instead of main backend code is due to the fact
+// that we store page and group data in YJS documents in the same way as they are stored in the database.
+// Therefore, we need to expose this conversion to the client so that it can consume data from YJS documents.
+//
+// Please do not put more DTO conversion here unless you know what you're doing.
+
+export function elementGroupsToDocumentationGroupStructureDTOV1(
+  groups: DocumentationGroupV1[],
+  pages: (DocumentationPageV1 | DocumentationPageV2)[]
+): DTODocumentationGroupStructureV1[] {
+  const childrenIdsMap = calculateChildrenIdsMapV1(pages, groups);
+
+  return groups.map(group => elementGroupToDocumentationGroupStructureDTOV1(group, childrenIdsMap));
+}
+
+export function elementGroupsToDocumentationGroupDTOV1(
+  groups: DocumentationGroupV1[],
+  pages: (DocumentationPageV1 | DocumentationPageV2)[]
+): DTODocumentationGroupV1[] {
+  const childrenIdsMap = calculateChildrenIdsMapV1(pages, groups);
+
+  return groups.map(group => {
+    return {
+      ...elementGroupToDocumentationGroupStructureDTOV1(group, childrenIdsMap),
+      configuration: documentationItemConfigurationToDTOV1(group.data?.configuration),
+    };
+  });
+}
+
+export function elementGroupsToDocumentationGroupFixedConfigurationDTOV1(
+  groups: DocumentationGroupV1[],
+  pages: (DocumentationPageV1 | DocumentationPageV2)[]
+): DTODocumentationGroupV1[] {
+  const childrenIdsMap = calculateChildrenIdsMapV1(pages, groups);
+
+  const { groups: fixedGroups } = applyPrivacyConfigurationToNestedItems<
+    DocumentationPageV1 | DocumentationPageV2,
+    DocumentationGroupV1,
+    DocumentationItemConfigurationV1
+  >(pages, groups, getDtoDefaultItemConfigurationV1);
+
+  return fixedGroups.map(group => {
+    const configuration = documentationItemConfigurationToDTOV1(group.data?.configuration);
+
+    return {
+      ...elementGroupToDocumentationGroupStructureDTOV1(group, childrenIdsMap),
+      // backward compatibility with custom doc exporters, anyway these groups will not be shown, so we can adjust title
+      title: configuration.isHidden && !group.meta.name.startsWith("_") ? "_" + group.meta.name : group.meta.name,
+      configuration,
+    };
+  });
+}
+
+function elementGroupToDocumentationGroupStructureDTOV1(
+  group: DocumentationGroupV1,
+  childrenIdsMap: Map<string, string[]>
+): DTODocumentationGroupStructureV1 {
+  const childrenIds = childrenIdsMap.get(group.persistentId) ?? [];
+
+  if (!group.shortPersistentId) {
+    throw new Error(`Short persistent id is required for docs groups, group id: ${group.id}`);
+  }
+
+  return {
+    id: group.id,
+    designSystemVersionId: group.designSystemVersionId,
+    persistentId: group.persistentId,
+    slug: group.slug,
+    userSlug: group.userSlug,
+    createdAt: group.createdAt,
+    updatedAt: group.updatedAt,
+    title: group.meta.name,
+    childrenIds: childrenIds,
+    isRoot: !group.parentPersistentId,
+    groupBehavior: group.data?.behavior ?? "Group",
+    shortPersistentId: group.shortPersistentId,
+    type: "Group",
+  };
+}
+
+function calculateChildrenIdsMapV1(
+  elements: { persistentId: string; parentPersistentId: string; sortOrder: number }[],
+  groups: DocumentationGroupV1[]
+): Map<string, string[]> {
+  const byParentId = groupBy([...elements, ...groups], e => e.parentPersistentId);
+
+  const childrenIdsMap = new Map<string, string[]>();
+
+  for (const [parentPersistentId, children] of byParentId) {
+    if (!parentPersistentId) continue;
+    children.sort((lhs, rhs) => lhs.sortOrder - rhs.sortOrder);
+
+    childrenIdsMap.set(
+      parentPersistentId,
+      children.map(c => c.persistentId)
+    );
+  }
+
+  return childrenIdsMap;
+}

package/src/api/conversion/documentation/documentation-group-v2-to-dto.ts

@@ -0,0 +1,91 @@
+import { DocumentationItemConfigurationV2, DocumentationPageV1, groupBy } from "@supernova-studio/model";
+import { VersionRoomDocsPage, VersionRoomDocsPageGroup } from "../../../yjs/version-room/types";
+import { LocalDocsPage, LocalDocsPageGroup } from "../../../sync/types";
+import { DTODocumentationGroupV2 } from "../../dto";
+import {
+  documentationItemConfigurationToDTOV2,
+  getDtoDefaultItemConfigurationV2,
+} from "./documentation-item-configuration-v2-to-dto";
+import { applyPrivacyConfigurationToNestedItems } from "./documentation-page-to-dto-utils";
+
+type DocsPage = LocalDocsPage | VersionRoomDocsPage;
+type DocsPageGroup = LocalDocsPageGroup | VersionRoomDocsPageGroup;
+
+// The fact that DTO conversion is located here instead of main backend code is due to the fact
+// that we store page and group data in YJS documents in the same way as they are stored in the database.
+// Therefore, we need to expose this conversion to the client so that it can consume data from YJS documents.
+//
+// Please do not put more DTO conversion here unless you know what you're doing.
+
+export function elementGroupsToDocumentationGroupDTOV2(
+  groups: DocsPageGroup[],
+  pages: (DocumentationPageV1 | DocsPage)[]
+): DTODocumentationGroupV2[] {
+  const childrenIdsMap = calculateChildrenIdsMapV2(pages, groups);
+
+  return groups.map(group => elementGroupToDocumentationGroupStructureDTOV2(group, childrenIdsMap));
+}
+
+export function elementGroupsToDocumentationGroupFixedConfigurationDTOV2(
+  groups: DocsPageGroup[],
+  pages: (DocumentationPageV1 | DocsPage)[]
+): DTODocumentationGroupV2[] {
+  const childrenIdsMap = calculateChildrenIdsMapV2(pages, groups);
+
+  const { groups: fixedGroups } = applyPrivacyConfigurationToNestedItems<
+    DocumentationPageV1 | DocsPage,
+    DocsPageGroup,
+    DocumentationItemConfigurationV2
+  >(pages, groups, getDtoDefaultItemConfigurationV2);
+
+  return fixedGroups.map(group => elementGroupToDocumentationGroupStructureDTOV2(group, childrenIdsMap));
+}
+
+function elementGroupToDocumentationGroupStructureDTOV2(
+  group: DocsPageGroup,
+  childrenIdsMap: Map<string, string[]>
+): DTODocumentationGroupV2 {
+  const childrenIds = childrenIdsMap.get(group.persistentId) ?? [];
+
+  if (!group.shortPersistentId) {
+    throw new Error(`Short persistent id is required for docs groups, group id: ${group.persistentId}`);
+  }
+
+  return {
+    id: "to_be_removed",
+    designSystemVersionId: group.designSystemVersionId,
+    persistentId: group.persistentId,
+    slug: group.slug,
+    userSlug: group.userSlug,
+    createdAt: group.createdAt,
+    updatedAt: group.updatedAt,
+    title: group.meta.name,
+    configuration: documentationItemConfigurationToDTOV2(group?.data?.configuration),
+    childrenIds: childrenIds,
+    isRoot: !group.parentPersistentId,
+    groupBehavior: group.data?.behavior ?? "Group",
+    shortPersistentId: group.shortPersistentId,
+    type: "Group",
+  };
+}
+
+function calculateChildrenIdsMapV2(
+  elements: { persistentId: string; parentPersistentId: string; sortOrder: number }[],
+  groups: DocsPageGroup[]
+): Map<string, string[]> {
+  const byParentId = groupBy([...elements, ...groups], e => e.parentPersistentId);
+
+  const childrenIdsMap = new Map<string, string[]>();
+
+  for (const [parentPersistentId, children] of byParentId) {
+    if (!parentPersistentId) continue;
+    children.sort((lhs, rhs) => lhs.sortOrder - rhs.sortOrder);
+
+    childrenIdsMap.set(
+      parentPersistentId,
+      children.map(c => c.persistentId)
+    );
+  }
+
+  return childrenIdsMap;
+}

package/src/api/conversion/documentation/documentation-item-configuration-v1-to-dto.ts

@@ -0,0 +1,52 @@
+import {
+  ColorTokenData,
+  DocumentationItemConfigurationV1,
+  DocumentationItemHeaderAlignment,
+  DocumentationItemHeaderImageScaleType,
+} from "@supernova-studio/model";
+import { DTODocumentationItemConfigurationV1 } from "../../dto";
+
+export const getDtoDefaultItemConfigurationV1 = () =>
+  ({
+    showSidebar: true,
+    isHidden: false,
+    isPrivate: false,
+    header: {
+      alignment: DocumentationItemHeaderAlignment.Left,
+      backgroundImageScaleType: DocumentationItemHeaderImageScaleType.AspectFill,
+      description: "",
+      showBackgroundOverlay: false,
+      showCoverText: true,
+    },
+  } as const);
+
+export function documentationItemConfigurationToDTOV1(
+  config: DocumentationItemConfigurationV1 | undefined
+): DTODocumentationItemConfigurationV1 {
+  const dtoDefaultItemConfigurationV1 = getDtoDefaultItemConfigurationV1();
+  if (!config) return dtoDefaultItemConfigurationV1;
+
+  const { backgroundColor, foregroundColor, ...headerRest } = config.header;
+
+  return {
+    showSidebar: config.showSidebar,
+    isHidden: config.isHidden ?? dtoDefaultItemConfigurationV1.isHidden,
+    isPrivate: config.isPrivate ?? dtoDefaultItemConfigurationV1.isPrivate,
+    header: {
+      ...headerRest,
+      backgroundColor: colorToDTOV1(backgroundColor ?? undefined),
+      foregroundColor: colorToDTOV1(foregroundColor ?? undefined),
+    },
+  };
+}
+
+function colorToDTOV1(color: ColorTokenData | undefined) {
+  if (!color) return undefined;
+  if (color.aliasTo) return { aliasTo: color.aliasTo };
+  if (!color.value) return undefined;
+
+  if (typeof color.value === "string") return { value: color.value };
+  if (typeof color.value.color === "string") return { value: color.value.color };
+
+  return undefined;
+}

package/src/api/conversion/documentation/documentation-item-configuration-v2-to-dto.ts

@@ -0,0 +1,34 @@
+import {
+  DocumentationItemConfigurationV2,
+  DocumentationItemHeaderAlignment,
+  DocumentationItemHeaderImageScaleType,
+} from "@supernova-studio/model";
+import { DTODocumentationItemConfigurationV2 } from "../../dto/elements/documentation/item-configuration-v2";
+
+export const getDtoDefaultItemConfigurationV2 = () =>
+  ({
+    showSidebar: true,
+    isHidden: false,
+    isPrivate: false,
+    header: {
+      alignment: DocumentationItemHeaderAlignment.Left,
+      backgroundImageScaleType: DocumentationItemHeaderImageScaleType.AspectFill,
+      description: "",
+      showBackgroundOverlay: false,
+      showCoverText: true,
+    },
+  } as const);
+
+export function documentationItemConfigurationToDTOV2(
+  config: DocumentationItemConfigurationV2 | undefined
+): DTODocumentationItemConfigurationV2 {
+  const dtoDefaultItemConfigurationV2 = getDtoDefaultItemConfigurationV2();
+  if (!config) return dtoDefaultItemConfigurationV2;
+
+  return {
+    header: config.header,
+    isHidden: config.isHidden ?? dtoDefaultItemConfigurationV2.isHidden,
+    isPrivate: config.isPrivate ?? dtoDefaultItemConfigurationV2.isPrivate,
+    showSidebar: config.showSidebar,
+  };
+}