feat(validatePreviewUrl): add studioPreviewPerspective

packages/preview-url-secret/src/parsePreviewUrl.test.ts

@@ -1,5 +1,9 @@
 import {expect, test} from 'vitest'
-import {urlSearchParamPreviewPathname, urlSearchParamPreviewSecret} from './constants'
+import {
+  urlSearchParamPreviewPathname,
+  urlSearchParamPreviewPerspective,
+  urlSearchParamPreviewSecret,
+} from './constants'
 import {parsePreviewUrl} from './parsePreviewUrl'
 
 test('handles absolute URLs', () => {
@@ -9,16 +13,19 @@ test('handles absolute URLs', () => {
   expect(parsePreviewUrl(unsafe.toString())).toEqual({
     redirectTo: '/preview?foo=bar',
     secret: 'abc123',
+    studioPreviewPerspective: null,
   })
 })
 
 test('handles relative URLs', () => {
   const unsafe = new URL('/api/draft', 'http://localhost')
   unsafe.searchParams.set(urlSearchParamPreviewSecret, 'abc123')
   unsafe.searchParams.set(urlSearchParamPreviewPathname, '/preview?foo=bar')
+  unsafe.searchParams.set(urlSearchParamPreviewPerspective, 'published')
   expect(parsePreviewUrl(`${unsafe.pathname}${unsafe.search}`)).toEqual({
     redirectTo: '/preview?foo=bar',
     secret: 'abc123',
+    studioPreviewPerspective: 'published',
   })
 })
 
@@ -29,6 +36,7 @@ test('includes hash', () => {
   expect(parsePreviewUrl(unsafe.toString())).toEqual({
     redirectTo: '/preview?foo=bar#heading1',
     secret: 'abc123',
+    studioPreviewPerspective: null,
   })
 })
 
@@ -42,5 +50,6 @@ test('strips origin from redirect', () => {
   expect(parsePreviewUrl(unsafe.toString())).toEqual({
     redirectTo: '/preview?foo=bar',
     secret: 'abc123',
+    studioPreviewPerspective: null,
   })
 })

packages/preview-url-secret/src/parsePreviewUrl.ts

@@ -1,4 +1,8 @@
-import {urlSearchParamPreviewPathname, urlSearchParamPreviewSecret} from './constants'
+import {
+  urlSearchParamPreviewPathname,
+  urlSearchParamPreviewPerspective,
+  urlSearchParamPreviewSecret,
+} from './constants'
 import type {ParsedPreviewUrl} from './types'
 
 /**
@@ -10,11 +14,12 @@ export function parsePreviewUrl(unsafeUrl: string): ParsedPreviewUrl {
   if (!secret) {
     throw new Error('Missing secret')
   }
+  const studioPreviewPerspective = url.searchParams.get(urlSearchParamPreviewPerspective)
   let redirectTo = undefined
   const unsafeRedirectTo = url.searchParams.get(urlSearchParamPreviewPathname)
   if (unsafeRedirectTo) {
     const {pathname, search, hash} = new URL(unsafeRedirectTo, 'http://localhost')
     redirectTo = `${pathname}${search}${hash}`
   }
-  return {secret, redirectTo}
+  return {secret, redirectTo, studioPreviewPerspective}
 }

packages/preview-url-secret/src/types.ts

@@ -49,12 +49,19 @@ export interface PreviewUrlValidateUrlResult {
    * If the URL is valid, and the studio URL is known and valid, then its origin will be here
    */
   studioOrigin?: string
+  /**
+   * The initial perspective the Studio was using when starting to load the preview.
+   * It can change over time and should also be handled with `postMessage` listeners.
+   * The value can be arbitrary and has to be validated to make sure it's a valid perspective.
+   */
+  studioPreviewPerspective?: string | null
 }
 
 /** @internal */
 export interface ParsedPreviewUrl {
   secret: string
   redirectTo?: string
+  studioPreviewPerspective: string | null
 }
 
 /** @public */

packages/preview-url-secret/src/validatePreviewUrl.ts

@@ -37,6 +37,7 @@ export async function validatePreviewUrl(
     disableCacheNoStore,
   )
   const redirectTo = isValid ? parsedPreviewUrl.redirectTo : undefined
+  const studioPreviewPerspective = isValid ? parsedPreviewUrl.studioPreviewPerspective : undefined
   let studioOrigin: string | undefined
   if (isValid) {
     try {
@@ -52,7 +53,7 @@ export async function validatePreviewUrl(
     }
   }
 
-  return {isValid, redirectTo, studioOrigin}
+  return {isValid, redirectTo, studioOrigin, studioPreviewPerspective}
 }
 
 export type {PreviewUrlValidateUrlResult, SanityClientLike}