feat: description field for request parameters and headers (#4187)

* feat: key-value component added for reuse

* chore: inspection result added

* chore: add `HoppRESTRequest` schema `v7`

* feat: add `description` for field for REST request headers

* feat: add `description` for field for GraphQL request headers

* fix: synchronization logic b/w bulk edit context and the default view

- Add `HoppGQLRequest` schema `v6`.
- Fix pre-existing issue with changes in bulk edit context not immediately reflecting in the default GQL request headers view.

* feat: support importing `description` fields from external sources

* test: fix failing tests

* chore: include description field for computed headers

Headers computed based on authorization info & inherited entries.

* feat: add `description` field for headers at the collection level

Add `HoppCollection` schema `v3`.

* test: fix failing tests

* ci: update tests workflow target branch trigger

* chore: cleanup

* chore: cleanup

* chore: rely on type inference

---------

Co-authored-by: jamesgeorge007 <25279263+jamesgeorge007@users.noreply.github.com>
Co-authored-by: nivedin <nivedinp@gmail.com>

packages/hoppscotch-data/src/collection/index.ts

@@ -2,6 +2,7 @@ import { InferredEntity, createVersionedEntity } from "verzod"
 
 import V1_VERSION from "./v/1"
 import V2_VERSION from "./v/2"
+import V3_VERSION from "./v/3"
 
 import { z } from "zod"
 import { translateToNewRequest } from "../rest"
@@ -12,10 +13,11 @@ const versionedObject = z.object({
 })
 
 export const HoppCollection = createVersionedEntity({
-  latestVersion: 2,
+  latestVersion: 3,
   versionMap: {
     1: V1_VERSION,
     2: V2_VERSION,
+    3: V3_VERSION,
   },
   getVersion(data) {
     const versionCheck = versionedObject.safeParse(data)
@@ -31,7 +33,7 @@ export const HoppCollection = createVersionedEntity({
 
 export type HoppCollection = InferredEntity<typeof HoppCollection>
 
-export const CollectionSchemaVersion = 2
+export const CollectionSchemaVersion = 3
 
 /**
  * Generates a Collection object. This ignores the version number object

packages/hoppscotch-data/src/collection/v/2.ts

@@ -1,11 +1,15 @@
 import { defineVersion, entityReference } from "verzod"
 import { z } from "zod"
-import { HoppRESTRequest, HoppRESTAuth } from "../../rest"
-import { HoppGQLRequest, HoppGQLAuth, GQLHeader } from "../../graphql"
-import { V1_SCHEMA } from "./1"
-import { HoppRESTHeaders } from "../../rest/v/1"
 
-const baseCollectionSchema = z.object({
+import { HoppGQLRequest } from "../../graphql"
+import { GQLHeader } from "../../graphql/v/1"
+import { HoppGQLAuth } from "../../graphql/v/5"
+import { HoppRESTRequest } from "../../rest"
+import { HoppRESTHeaders } from "../../rest/v/1"
+import { HoppRESTAuth } from "../../rest/v/5"
+import { V1_SCHEMA } from "./1"
+
+export const v2_baseCollectionSchema = z.object({
   v: z.literal(2),
   id: z.optional(z.string()), // For Firestore ID data
 
@@ -23,17 +27,18 @@ const baseCollectionSchema = z.object({
   headers: z.union([HoppRESTHeaders, z.array(GQLHeader)]),
 })
 
-type Input = z.input<typeof baseCollectionSchema> & {
+type Input = z.input<typeof v2_baseCollectionSchema> & {
   folders: Input[]
 }
 
-type Output = z.output<typeof baseCollectionSchema> & {
+type Output = z.output<typeof v2_baseCollectionSchema> & {
   folders: Output[]
 }
 
-export const V2_SCHEMA: z.ZodType<Output, z.ZodTypeDef, Input> = baseCollectionSchema.extend({
-  folders: z.lazy(() => z.array(V2_SCHEMA)),
-})
+export const V2_SCHEMA: z.ZodType<Output, z.ZodTypeDef, Input> =
+  v2_baseCollectionSchema.extend({
+    folders: z.lazy(() => z.array(V2_SCHEMA)),
+  })
 
 export default defineVersion({
   initial: false,

packages/hoppscotch-data/src/collection/v/3.ts

@@ -0,0 +1,48 @@
+import { defineVersion } from "verzod"
+import { z } from "zod"
+
+import { GQLHeader as GQLHeaderV1 } from "../../graphql/v/1"
+import { GQLHeader as GQLHeaderV2 } from "../../graphql/v/6"
+import { HoppRESTHeaders as V1_HoppRESTHeaders } from "../../rest/v/1"
+import { HoppRESTHeaders as V2_HoppRESTHeaders } from "../../rest/v/7"
+import { v2_baseCollectionSchema, V2_SCHEMA } from "./2"
+
+const v3_baseCollectionSchema = v2_baseCollectionSchema.extend({
+  v: z.literal(3),
+  headers: z.union([V2_HoppRESTHeaders, z.array(GQLHeaderV2)]),
+})
+
+type Input = z.input<typeof v3_baseCollectionSchema> & {
+  folders: Input[]
+}
+
+type Output = z.output<typeof v3_baseCollectionSchema> & {
+  folders: Output[]
+}
+
+export const V3_SCHEMA: z.ZodType<Output, z.ZodTypeDef, Input> =
+  v3_baseCollectionSchema.extend({
+    folders: z.lazy(() => z.array(V3_SCHEMA)),
+  })
+
+export default defineVersion({
+  initial: false,
+  schema: V3_SCHEMA,
+  up(old: z.infer<typeof V2_SCHEMA>) {
+    const headers = (old.headers as V1_HoppRESTHeaders | GQLHeaderV1[]).map(
+      (header) => ({
+        ...header,
+        description: "",
+      })
+    )
+
+    // @ts-expect-error
+    const result: z.infer<typeof V3_SCHEMA> = {
+      ...old,
+      v: 3,
+      headers,
+    }
+
+    return result
+  },
+})

packages/hoppscotch-data/src/graphql/index.ts

@@ -5,33 +5,35 @@ import V2_VERSION from "./v/2"
 import V3_VERSION from "./v/3"
 import V4_VERSION from "./v/4"
 import V5_VERSION from "./v/5"
+import V6_VERSION from "./v/6"
 
-export { GQLHeader } from "./v/1"
 export {
   HoppGQLAuthBasic,
   HoppGQLAuthBearer,
-  HoppGQLAuthNone,
   HoppGQLAuthInherit,
+  HoppGQLAuthNone,
 } from "./v/2"
+export { GQLHeader } from "./v/6"
 
-export { HoppGQLAuthOAuth2, HoppGQLAuth } from "./v/5"
+export { HoppGQLAuth, HoppGQLAuthOAuth2 } from "./v/5"
 
 export { HoppGQLAuthAPIKey } from "./v/4"
 
-export const GQL_REQ_SCHEMA_VERSION = 5
+export const GQL_REQ_SCHEMA_VERSION = 6
 
 const versionedObject = z.object({
   v: z.number(),
 })
 
 export const HoppGQLRequest = createVersionedEntity({
-  latestVersion: 5,
+  latestVersion: 6,
   versionMap: {
     1: V1_VERSION,
     2: V2_VERSION,
     3: V3_VERSION,
     4: V4_VERSION,
     5: V5_VERSION,
+    6: V6_VERSION,
   },
   getVersion(x) {
     const result = versionedObject.safeParse(x)

packages/hoppscotch-data/src/graphql/v/6.ts

@@ -0,0 +1,37 @@
+import { defineVersion } from "verzod"
+import { z } from "zod"
+
+import { V5_SCHEMA } from "./5"
+
+export const GQLHeader = z.object({
+  key: z.string().catch(""),
+  value: z.string().catch(""),
+  active: z.boolean().catch(true),
+  description: z.string().catch(""),
+})
+
+export type GQLHeader = z.infer<typeof GQLHeader>
+
+export const V6_SCHEMA = V5_SCHEMA.extend({
+  v: z.literal(6),
+  headers: z.array(GQLHeader).catch([]),
+})
+
+export default defineVersion({
+  schema: V6_SCHEMA,
+  initial: false,
+  up(old: z.infer<typeof V6_SCHEMA>) {
+    const headers = old.headers.map((header) => {
+      return {
+        ...header,
+        description: "",
+      }
+    })
+
+    return {
+      ...old,
+      v: 6 as const,
+      headers,
+    }
+  },
+})

packages/hoppscotch-data/src/rest/index.ts

@@ -14,7 +14,8 @@ import V4_VERSION from "./v/4"
 import V5_VERSION from "./v/5"
 import V6_VERSION, { HoppRESTReqBody } from "./v/6"
 
-import { HoppRESTHeaders, HoppRESTParams } from "./v/1"
+import { HoppRESTHeaders, HoppRESTParams } from "./v/7"
+import V7_VERSION from "./v/7"
 
 import { HoppRESTRequestVariables } from "./v/2"
 import { HoppRESTAuth } from "./v/5"
@@ -27,7 +28,6 @@ export {
   HoppRESTAuthBearer,
   HoppRESTAuthInherit,
   HoppRESTAuthNone,
-  HoppRESTHeaders,
   HoppRESTReqBodyFormData,
 } from "./v/1"
 
@@ -48,6 +48,7 @@ export { HoppRESTAuthAPIKey } from "./v/4"
 export { HoppRESTRequestVariables } from "./v/2"
 
 export { HoppRESTReqBody } from "./v/6"
+export { HoppRESTHeaders } from "./v/7"
 
 const versionedObject = z.object({
   // v is a stringified number
@@ -55,7 +56,7 @@ const versionedObject = z.object({
 })
 
 export const HoppRESTRequest = createVersionedEntity({
-  latestVersion: 6,
+  latestVersion: 7,
   versionMap: {
     0: V0_VERSION,
     1: V1_VERSION,
@@ -64,6 +65,7 @@ export const HoppRESTRequest = createVersionedEntity({
     4: V4_VERSION,
     5: V5_VERSION,
     6: V6_VERSION,
+    7: V7_VERSION,
   },
   getVersion(data) {
     // For V1 onwards we have the v string storing the number
@@ -105,7 +107,7 @@ const HoppRESTRequestEq = Eq.struct<HoppRESTRequest>({
   ),
 })
 
-export const RESTReqSchemaVersion = "6"
+export const RESTReqSchemaVersion = "7"
 
 export type HoppRESTParam = HoppRESTRequest["params"][number]
 export type HoppRESTHeader = HoppRESTRequest["headers"][number]

packages/hoppscotch-data/src/rest/v/7.ts

@@ -0,0 +1,59 @@
+import { defineVersion } from "verzod"
+import { z } from "zod"
+
+import { V6_SCHEMA } from "./6"
+
+export const HoppRESTParams = z.array(
+  z.object({
+    key: z.string().catch(""),
+    value: z.string().catch(""),
+    active: z.boolean().catch(true),
+    description: z.string().catch(""),
+  })
+)
+
+export type HoppRESTParams = z.infer<typeof HoppRESTParams>
+
+export const HoppRESTHeaders = z.array(
+  z.object({
+    key: z.string().catch(""),
+    value: z.string().catch(""),
+    active: z.boolean().catch(true),
+    description: z.string().catch(""),
+  })
+)
+
+export type HoppRESTHeaders = z.infer<typeof HoppRESTHeaders>
+
+export const V7_SCHEMA = V6_SCHEMA.extend({
+  v: z.literal("7"),
+  params: HoppRESTParams,
+  headers: HoppRESTHeaders,
+})
+
+export default defineVersion({
+  schema: V7_SCHEMA,
+  initial: false,
+  up(old: z.infer<typeof V6_SCHEMA>) {
+    const params = old.params.map((param) => {
+      return {
+        ...param,
+        description: "",
+      }
+    })
+
+    const headers = old.headers.map((header) => {
+      return {
+        ...header,
+        description: "",
+      }
+    })
+
+    return {
+      ...old,
+      v: "7" as const,
+      params,
+      headers,
+    }
+  },
+})