@supernova-studio/client 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova-studio/client",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Supernova Data Models",
   "source": "src/index.ts",
   "main": "dist/index.js",

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

@@ -0,0 +1,20 @@
+import { documentationPagesToStructureDTOV2 } from "./documentation-page-v2-to-dto";
+import { elementGroupsToDocumentationGroupStructureDTO } from "./documentation-group-to-dto";
+import { DocumentationPageV2, ElementGroup } from "@supernova-studio/model";
+import { DTODocumentationHierarchyV2 } from "../../dto";
+
+// 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 documentationElementsToHierarchyDto(
+  docPages: DocumentationPageV2[],
+  docGroups: ElementGroup[]
+): DTODocumentationHierarchyV2 {
+  return {
+    pages: documentationPagesToStructureDTOV2(docPages, docGroups),
+    groups: elementGroupsToDocumentationGroupStructureDTO(docGroups, docPages),
+  };
+}

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

@@ -0,0 +1,83 @@
+import { defaultDocumentationItemHeader, DocumentationPageV1, groupBy } from "@supernova-studio/model";
+import { DocumentationPageV2 } from "@supernova-studio/model";
+import { ElementGroup } from "@supernova-studio/model";
+import { DTODocumentationGroup, DTODocumentationGroupStructure } from "../../dto";
+
+// 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 elementGroupsToDocumentationGroupStructureDTO(
+  groups: ElementGroup[],
+  pages: (DocumentationPageV1 | DocumentationPageV2)[]
+): DTODocumentationGroupStructure[] {
+  const childrenIdsMap = calculateChildrenIdsMap(pages, groups);
+
+  return groups.map(group => elementGroupToDocumentationGroupStructureDTO(group, childrenIdsMap));
+}
+
+export function elementGroupsToDocumentationGroupDTO(
+  groups: ElementGroup[],
+  pages: (DocumentationPageV1 | DocumentationPageV2)[]
+): DTODocumentationGroup[] {
+  const childrenIdsMap = calculateChildrenIdsMap(pages, groups);
+
+  return groups.map(group => {
+    return {
+      ...elementGroupToDocumentationGroupStructureDTO(group, childrenIdsMap),
+      configuration: group.data?.configuration ?? {
+        showSidebar: true,
+        header: defaultDocumentationItemHeader,
+      },
+    };
+  });
+}
+
+function elementGroupToDocumentationGroupStructureDTO(
+  group: ElementGroup,
+  childrenIdsMap: Map<string, string[]>
+): DTODocumentationGroupStructure {
+  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,
+  };
+}
+
+function calculateChildrenIdsMap(
+  elements: { persistentId: string; parentPersistentId: string; sortOrder: number }[],
+  groups: ElementGroup[]
+): 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-page-to-dto-utils.ts

@@ -0,0 +1,54 @@
+import { DocumentationPageV1, DocumentationPageV2, ElementGroup, slugify } from "@supernova-studio/model";
+import { mapByUnique } from "@supernova-studio/model";
+
+// 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 buildDocPagePublishPaths(
+  groups: ElementGroup[],
+  pages: (DocumentationPageV1 | DocumentationPageV2)[]
+): Map<string, string> {
+  const groupPersistentIdToGroupMap = mapByUnique(groups, group => group.persistentId);
+  const result = new Map<string, string>();
+
+  for (const page of pages) {
+    const parentChain = calculateElementParentChain(page.parentPersistentId, groupPersistentIdToGroupMap);
+
+    let pathV1 = `${page.userSlug || page.slug}.html`;
+    let pathV2 = `${slugify(page.meta.name)}-${page.shortPersistentId}`;
+
+    for (const parent of parentChain) {
+      if (!parent.parentPersistentId) continue;
+
+      pathV1 = `${parent.userSlug || parent.slug}/${pathV1}`;
+      pathV2 = `${slugify(parent.meta.name)}/${pathV2}`;
+    }
+
+    pathV1 = `/${pathV1}`;
+    pathV2 = `/${pathV2}`;
+
+    result.set(page.persistentId, pathV2);
+  }
+
+  return result;
+}
+
+export function calculateElementParentChain(
+  elementParentPersistentId: string,
+  groupPersistentIdToGroupMap: Map<string, ElementGroup>
+): ElementGroup[] {
+  const result: ElementGroup[] = [];
+
+  let parentId: string | undefined = elementParentPersistentId;
+  while (parentId) {
+    const parent = groupPersistentIdToGroupMap.get(parentId);
+    if (parent) result.push(parent);
+
+    parentId = parent?.parentPersistentId;
+  }
+
+  return result;
+}

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

@@ -0,0 +1,43 @@
+import { SupernovaException } from "@supernova-studio/model";
+import { defaultDocumentationItemHeader, DocumentationPageV1 } from "@supernova-studio/model";
+import { ElementGroup } from "@supernova-studio/model";
+import { buildDocPagePublishPaths } from "./documentation-page-to-dto-utils";
+import { DocumentationPageV1DTO } from "../../dto";
+
+// 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 documentationPagesToDTOV1(
+  pages: DocumentationPageV1[],
+  groups: ElementGroup[]
+): DocumentationPageV1DTO[] {
+  const pathsMap = buildDocPagePublishPaths(groups, pages);
+
+  return pages.map(page => {
+    let path = pathsMap.get(page.persistentId);
+    if (!path) throw SupernovaException.conflict(`Path for page ${page.id} was not calculated`);
+
+    if (path.startsWith("/")) path = path.substring(1);
+
+    return {
+      id: page.id,
+      designSystemVersionId: page.designSystemVersionId,
+      persistentId: page.persistentId,
+      shortPersistentId: page.shortPersistentId,
+      title: page.meta.name,
+      blocks: page.data.blocks,
+      slug: page.slug,
+      userSlug: page.userSlug,
+      configuration: page.data.configuration ?? {
+        showSidebar: true,
+        header: defaultDocumentationItemHeader,
+      },
+      createdAt: page.createdAt,
+      updatedAt: page.updatedAt,
+      path: path,
+    };
+  });
+}

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

@@ -0,0 +1,57 @@
+import { defaultDocumentationItemHeader, DocumentationPageV2 } from "@supernova-studio/model";
+import { ElementGroup } from "@supernova-studio/model";
+import { buildDocPagePublishPaths } from "./documentation-page-to-dto-utils";
+import { DTODocumentationPageStructureV2, DTODocumentationPageV2 } from "../../dto";
+
+// 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 documentationPagesToStructureDTOV2(
+  pages: DocumentationPageV2[],
+  groups: ElementGroup[]
+): DTODocumentationPageStructureV2[] {
+  const pathsMap = buildDocPagePublishPaths(groups, pages);
+  return pages.map(page => documentationPageToStructureDTOV2(page, pathsMap));
+}
+
+export function documentationPagesToDTOV2(
+  pages: DocumentationPageV2[],
+  groups: ElementGroup[]
+): DTODocumentationPageV2[] {
+  const pathsMap = buildDocPagePublishPaths(groups, pages);
+  return pages.map(page => {
+    return {
+      ...documentationPageToStructureDTOV2(page, pathsMap),
+      configuration: page.data.configuration ?? {
+        showSidebar: true,
+        header: defaultDocumentationItemHeader,
+      },
+    };
+  });
+}
+
+function documentationPageToStructureDTOV2(
+  page: DocumentationPageV2,
+  pagePathMap: Map<string, string>
+): DTODocumentationPageStructureV2 {
+  let path = pagePathMap.get(page.persistentId);
+  if (!path) throw new Error(`Path for page ${page.id} was not calculated`);
+
+  if (path.startsWith("/")) path = path.substring(1);
+
+  return {
+    id: page.id,
+    designSystemVersionId: page.designSystemVersionId,
+    persistentId: page.persistentId,
+    shortPersistentId: page.shortPersistentId,
+    title: page.meta.name,
+    slug: page.slug,
+    userSlug: page.userSlug,
+    createdAt: page.createdAt,
+    updatedAt: page.updatedAt,
+    path: path,
+  };
+}

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

@@ -0,0 +1,5 @@
+export * from "./documentation-elements-to-hierarchy-v2-dto";
+export * from "./documentation-group-to-dto";
+export * from "./documentation-page-to-dto-utils";
+export * from "./documentation-page-v1-to-dto";
+export * from "./documentation-page-v2-to-dto";

package/src/api/conversion/index.ts

@@ -0,0 +1 @@
+export * from "./documentation";

package/src/api/dto/{design-system.ts → design-systems/design-system.ts}

@@ -1,11 +1,15 @@
 import { DesignSystem, ObjectMeta } from "@supernova-studio/model";
 import { z } from "zod";
 
-export const DesignSystemDTO = DesignSystem.omit({
+//
+// Read
+//
+
+export const DTODesignSystem = DesignSystem.omit({
   name: true,
   description: true,
 }).extend({
   meta: ObjectMeta,
 });
 
-export type DesignSystemDTO = z.infer<typeof DesignSystemDTO>;
+export type DTODesignSystem = z.infer<typeof DTODesignSystem>;

package/src/api/dto/design-systems/index.ts

@@ -0,0 +1 @@
+export * from "./design-system";

package/src/api/dto/elements/documentation/group-action.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import {
+  DTOCreateDocumentationGroupInput,
+  DTODeleteDocumentationGroupInput,
+  DTODocumentationGroup,
+  DTODuplicateDocumentationGroupInput,
+  DTOUpdateDocumentationGroupInput,
+} from "./group";
+
+//
+// Read
+//
+
+export const DTODocumentationGroupCreateActionOutputV2 = z.object({
+  type: z.literal("DocumentationGroupCreate"),
+  output: DTODocumentationGroup,
+});
+
+export const DTODocumentationGroupUpdateActionOutputV2 = z.object({
+  type: z.literal("DocumentationGroupUpdate"),
+  output: DTODocumentationGroup,
+});
+
+export const DTODocumentationGroupDuplicateActionOutputV2 = z.object({
+  type: z.literal("DocumentationGroupDuplicate"),
+  output: DTODocumentationGroup,
+});
+
+export const DTODocumentationGroupDeleteActionOutputV2 = z.object({
+  type: z.literal("DocumentationGroupDelete"),
+  output: z.string(),
+});
+
+export type DTODocumentationGroupCreateActionOutputV2 = z.infer<typeof DTODocumentationGroupCreateActionOutputV2>;
+export type DTODocumentationGroupUpdateActionOutputV2 = z.infer<typeof DTODocumentationGroupUpdateActionOutputV2>;
+export type DTODocumentationGroupDuplicateActionOutputV2 = z.infer<typeof DTODocumentationGroupDuplicateActionOutputV2>;
+export type DTODocumentationGroupDeleteActionOutputV2 = z.infer<typeof DTODocumentationGroupDeleteActionOutputV2>;
+
+//
+// Write
+//
+
+export const DTODocumentationGroupCreateActionInputV2 = z.object({
+  type: z.literal("DocumentationGroupCreate"),
+  input: DTOCreateDocumentationGroupInput,
+});
+
+export const DTODocumentationGroupUpdateActionInputV2 = z.object({
+  type: z.literal("DocumentationGroupUpdate"),
+  input: DTOUpdateDocumentationGroupInput,
+});
+
+export const DTODocumentationGroupDuplicateActionInputV2 = z.object({
+  type: z.literal("DocumentationGroupDuplicate"),
+  input: DTODuplicateDocumentationGroupInput,
+});
+
+export const DTODocumentationGroupDeleteActionInputV2 = z.object({
+  type: z.literal("DocumentationGroupDelete"),
+  input: DTODeleteDocumentationGroupInput,
+});
+
+export type DTODocumentationGroupCreateActionInputV2 = z.infer<typeof DTODocumentationGroupCreateActionInputV2>;
+export type DTODocumentationGroupUpdateActionInputV2 = z.infer<typeof DTODocumentationGroupUpdateActionInputV2>;
+export type DTODocumentationGroupDuplicateActionInputV2 = z.infer<typeof DTODocumentationGroupDuplicateActionInputV2>;
+export type DTODocumentationGroupDeleteActionInputV2 = z.infer<typeof DTODocumentationGroupDeleteActionInputV2>;

package/src/api/dto/elements/documentation/group-bulk-action.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import {
+  DTOCreateDocumentationGroupInput,
+  DTODocumentationGroup,
+  DTODuplicateDocumentationGroupInput,
+  DTOUpdateDocumentationGroupInput,
+} from "./group";
+
+//
+// Read
+//
+
+export const DTODocumentationGroupBulkActionOutputV2 = z.object({
+  created: z.array(DTODocumentationGroup),
+  updated: z.array(DTODocumentationGroup),
+  deleted: z.array(z.string()),
+});
+
+export type DTODocumentationGroupBulkActionOutputV2 = z.infer<typeof DTODocumentationGroupBulkActionOutputV2>;
+
+//
+// Write
+//
+
+export const DTODocumentationGroupBulkActionInputV2 = z.object({
+  create: z.array(DTOCreateDocumentationGroupInput).optional(),
+  update: z.array(DTOUpdateDocumentationGroupInput).optional(),
+  duplicate: z.array(DTODuplicateDocumentationGroupInput).optional(),
+  delete: z.array(z.string()).optional(),
+});
+
+export type DTODocumentationGroupBulkActionInputV2 = z.infer<typeof DTODocumentationGroupBulkActionInputV2>;

package/src/api/dto/elements/documentation/group.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { DocumentationGroupBehavior, DocumentationItemConfiguration, ElementGroup } from "@supernova-studio/model";
+
+//
+// Read
+//
+
+/**
+ * Structure DTO is element properties minus element data (in other words data required
+ * to display the element in the left panel)
+ */
+export const DTODocumentationGroupStructure = ElementGroup.omit({
+  sortOrder: true,
+  parentPersistentId: true,
+  brandPersistentId: true,
+  meta: true,
+  childType: true,
+  data: true,
+  shortPersistentId: true,
+}).extend({
+  title: z.string(),
+  isRoot: z.boolean(),
+  childrenIds: z.array(z.string()),
+  groupBehavior: DocumentationGroupBehavior,
+  shortPersistentId: z.string(),
+});
+
+export const DTODocumentationGroup = DTODocumentationGroupStructure.extend({
+  configuration: DocumentationItemConfiguration,
+});
+
+export type DTODocumentationGroupStructure = z.infer<typeof DTODocumentationGroupStructure>;
+export type DTODocumentationGroup = z.infer<typeof DTODocumentationGroup>;
+
+//
+// Write
+//
+
+export const DTOCreateDocumentationGroupInput = z.object({
+  // Identifier
+  persistentId: z.string().uuid(),
+
+  // Group properties
+  title: z.string(),
+  configuration: DocumentationItemConfiguration.optional(),
+  groupBehavior: DocumentationGroupBehavior,
+
+  // Group placement properties
+  afterPersistentId: z.string().uuid().optional(),
+  parentPersistentId: z.string().uuid(),
+});
+
+export const DTOUpdateDocumentationGroupInput = z.object({
+  // Identifier of the group to update
+  id: z.string().uuid(),
+
+  // Group properties
+  title: z.string().optional(),
+  configuration: DocumentationItemConfiguration.optional(),
+});
+
+export const DTODuplicateDocumentationGroupInput = z.object({
+  // Identifier of the group to duplicate from
+  id: z.string(),
+
+  // New group persistent id
+  persistentId: z.string().uuid(),
+
+  // Group placement properties
+  afterPersistentId: z.string().uuid().optional(),
+  parentPersistentId: z.string().uuid(),
+});
+
+export const DTODeleteDocumentationGroupInput = z.object({
+  // Identifier
+  id: z.string(),
+
+  // Deletion options
+  deleteSubtree: z.boolean().default(false),
+});
+
+export type DTOCreateDocumentationGroupInput = z.infer<typeof DTOCreateDocumentationGroupInput>;
+export type DTOUpdateDocumentationGroupInput = z.infer<typeof DTOUpdateDocumentationGroupInput>;
+export type DTODuplicateDocumentationGroupInput = z.infer<typeof DTODuplicateDocumentationGroupInput>;
+export type DTODeleteDocumentationGroupInput = z.infer<typeof DTODeleteDocumentationGroupInput>;

package/src/api/dto/elements/documentation/index.ts

@@ -0,0 +1,7 @@
+export * from "./group-action";
+export * from "./group-bulk-action";
+export * from "./group";
+export * from "./page-actions-v2";
+export * from "./page-bulk-action-v2";
+export * from "./page-v1";
+export * from "./page-v2";

package/src/api/dto/elements/documentation/page-actions-v2.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import {
+  DTOCreateDocumentationPageInputV2,
+  DTODeleteDocumentationPageInputV2,
+  DTODocumentationPageV2,
+  DTODuplicateDocumentationPageInputV2,
+  DTOUpdateDocumentationPageInputV2,
+} from "./page-v2";
+
+//
+// Read
+//
+
+export const DTODocumentationPageCreateActionOutputV2 = z.object({
+  type: z.literal("DocumentationPageCreate"),
+  output: DTODocumentationPageV2,
+});
+
+export const DTODocumentationPageUpdateActionOutputV2 = z.object({
+  type: z.literal("DocumentationPageUpdate"),
+  output: DTODocumentationPageV2,
+});
+
+export const DTODocumentationPageDuplicateActionOutputV2 = z.object({
+  type: z.literal("DocumentationPageDuplicate"),
+  output: DTODocumentationPageV2,
+});
+
+export const DTODocumentationPageDeleteActionOutputV2 = z.object({
+  type: z.literal("DocumentationPageDelete"),
+  output: z.string(),
+});
+
+export type DTODocumentationPageCreateActionOutputV2 = z.infer<typeof DTODocumentationPageCreateActionOutputV2>;
+export type DTODocumentationPageUpdateActionOutputV2 = z.infer<typeof DTODocumentationPageUpdateActionOutputV2>;
+export type DTODocumentationPageDuplicateActionOutputV2 = z.infer<typeof DTODocumentationPageDuplicateActionOutputV2>;
+export type DTODocumentationPageDeleteActionOutputV2 = z.infer<typeof DTODocumentationPageDeleteActionOutputV2>;
+
+//
+// Write
+//
+
+export const DTODocumentationPageCreateActionInputV2 = z.object({
+  type: z.literal("DocumentationPageCreate"),
+  input: DTOCreateDocumentationPageInputV2,
+});
+
+export const DTODocumentationPageUpdateActionInputV2 = z.object({
+  type: z.literal("DocumentationPageUpdate"),
+  input: DTOUpdateDocumentationPageInputV2,
+});
+
+export const DTODocumentationPageDuplicateActionInputV2 = z.object({
+  type: z.literal("DocumentationPageDuplicate"),
+  input: DTODuplicateDocumentationPageInputV2,
+});
+
+export const DTODocumentationPageDeleteActionInputV2 = z.object({
+  type: z.literal("DocumentationPageDelete"),
+  input: DTODeleteDocumentationPageInputV2,
+});
+
+export type DTODocumentationPageCreateActionInputV2 = z.infer<typeof DTODocumentationPageCreateActionInputV2>;
+export type DTODocumentationPageUpdateActionInputV2 = z.infer<typeof DTODocumentationPageUpdateActionInputV2>;
+export type DTODocumentationPageDuplicateActionInputV2 = z.infer<typeof DTODocumentationPageDuplicateActionInputV2>;
+export type DTODocumentationPageDeleteActionInputV2 = z.infer<typeof DTODocumentationPageDeleteActionInputV2>;

package/src/api/dto/elements/documentation/page-bulk-action-v2.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import {
+  DTOCreateDocumentationPageInputV2,
+  DTODeleteDocumentationPageInputV2,
+  DTODocumentationPageV2,
+  DTODuplicateDocumentationPageInputV2,
+  DTOUpdateDocumentationPageInputV2,
+} from "./page-v2";
+
+//
+// Read
+//
+
+export const DTODocumentationPageBulkActionOutputV2 = z.object({
+  created: z.array(DTODocumentationPageV2),
+  updated: z.array(DTODocumentationPageV2),
+  deleted: z.array(z.string()),
+});
+
+export type DTODocumentationPageBulkActionOutputV2 = z.infer<typeof DTODocumentationPageBulkActionOutputV2>;
+
+//
+// Write
+//
+
+export const DTODocumentationPageBulkActionInputV2 = z.object({
+  create: z.array(DTOCreateDocumentationPageInputV2).optional(),
+  update: z.array(DTOUpdateDocumentationPageInputV2).optional(),
+  duplicate: z.array(DTODuplicateDocumentationPageInputV2).optional(),
+  delete: z.array(DTODeleteDocumentationPageInputV2).optional(),
+});
+
+export type DTODocumentationPageBulkActionInputV2 = z.infer<typeof DTODocumentationPageBulkActionInputV2>;

package/src/api/dto/{documentation-v1.ts → elements/documentation/page-v1.ts}

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { DocumentationPageV1 } from "@supernova-studio/model";
 
+//
+// Read
+//
+
 export const DocumentationPageV1DTO = DocumentationPageV1.omit({
   data: true,
   meta: true,