Merge branch 'feat/exo' into feat/exo-fragment-types

Author: michaelphamcf

lib/adapters/REST/endpoints/experience.ts

@@ -57,9 +57,14 @@ export const update: RestEndpoint<'Experience', 'update'> = (
   rawData: UpdateExperienceProps,
   headers?: RawAxiosRequestHeaders,
 ) => {
-  const data: SetOptional<typeof rawData, 'sys'> & { componentTypeId?: string } = copy(rawData)
+  const data: SetOptional<typeof rawData, 'sys'> & {
+    componentTypeId?: string
+    templateId?: string
+  } = copy(rawData)
   if (rawData.sys.componentType) {
     data.componentTypeId = rawData.sys.componentType.sys.id
+  } else if (rawData.sys.template) {
+    data.templateId = rawData.sys.template.sys.id
   }
   delete data.sys
   return raw.put<ExperienceProps>(http, getBaseUrl(params) + `/${params.experienceId}`, data, {

lib/common-types.ts

@@ -377,14 +377,21 @@ export interface MetadataProps {
 }
 
 /**
- * Metadata shape for ExO entities (ComponentType, Experience/View, Template).
+ * Base metadata shape for ExO entities (ComponentType, Template).
+ * Mirrors upstream MetadataSchema: tags and concepts only.
  * - tags: optional (upstream MetadataSchema.tags is z.optional as of SPA-3821)
  * - concepts: optional taxonomy concept links
- * - name: optional display name for variant labeling (SPA-3939)
  */
 export interface ExoMetadataProps {
   tags?: Link<'Tag'>[]
   concepts?: Link<'TaxonomyConcept'>[]
+}
+
+/**
+ * Extended metadata shape for Experience entities only.
+ * Adds name? for variant labeling (SPA-3939), mirroring upstream ExperienceMetadata.
+ */
+export interface ExperienceMetadataProps extends ExoMetadataProps {
   name?: string
 }
 

lib/entities/component-type.ts

@@ -24,7 +24,7 @@ export type ComponentTypeViewport = {
 export type ComponentTypeContentProperty = {
   id: string
   name: string
-  type: string
+  type: 'String' | 'Number' | 'Boolean'
   required: boolean
   defaultValue?: unknown
 }
@@ -53,7 +53,6 @@ export type ComponentTypeDesignProperty = {
   validations?: {
     in?: ComponentTypeDesignPropertyValidation[]
   }
-  designTokenSet: string[]
 }
 
 // Dimension key map

lib/entities/experience.ts

@@ -1,7 +1,7 @@
 import type {
   CursorPaginatedCollectionProp,
   CursorPaginationParams,
-  ExoMetadataProps,
+  ExperienceMetadataProps,
   Link,
 } from '../common-types'
 import type {
@@ -35,6 +35,9 @@ export type ExperienceSys = {
   updatedAt: string
   createdBy: Link<'User'>
   updatedBy: Link<'User'>
+  archivedAt?: string
+  archivedBy?: Link<'User'>
+  archivedVersion?: number
   variant?: string
   variantType?: string
   variantDimension?: string
@@ -54,7 +57,7 @@ type ExperienceCommonProps = {
   designProperties: Record<string, DimensionedDesignPropertyValue>
   dimensionKeyMap: ExperienceDimensionKeyMap
   contentBindings?: ExperienceContentBindings
-  metadata?: ExoMetadataProps
+  metadata?: ExperienceMetadataProps
   slots?: Record<string, Array<FragmentNode | InlineFragmentNode>>
 }
 
@@ -72,10 +75,13 @@ export type ExperienceQueryOptions = CursorPaginationParams & {
 // Omit the payload entirely for a full publish (all locales).
 export type ExperienceLocalePublishPayload = { add: string[] } | { remove: string[] }
 
-// Create payload — no sys, uses componentTypeId instead of sys.componentType link
-export type CreateExperienceProps = ExperienceCommonProps & {
-  componentTypeId: string
-}
+// Create payload — no sys, uses either componentTypeId (component-type-backed) or
+// templateId (template-backed). The two fields are mutually exclusive.
+export type CreateExperienceProps = ExperienceCommonProps &
+  (
+    | { componentTypeId: string; templateId?: never }
+    | { templateId: string; componentTypeId?: never }
+  )
 
 export type UpdateExperienceProps = ExperienceProps
 

lib/plain/entities/experience.ts

@@ -60,6 +60,7 @@ export type ExperiencePlainClientAPI = {
    * @internal - Experimental endpoint, subject to breaking changes without notice
    * @example
    * ```javascript
+   * // Component-type-backed experience
    * const experience = await client.experience.create({
    *   spaceId: '<space_id>',
    *   environmentId: '<environment_id>',
@@ -72,6 +73,20 @@ export type ExperiencePlainClientAPI = {
    *   designProperties: {},
    *   dimensionKeyMap: { designProperties: {} },
    * });
+   *
+   * // Template-backed experience
+   * const experience = await client.experience.create({
+   *   spaceId: '<space_id>',
+   *   environmentId: '<environment_id>',
+   * }, {
+   *   name: 'My Template Experience',
+   *   description: 'A template-backed experience',
+   *   templateId: '<template_id>',
+   *   viewports: [],
+   *   contentProperties: {},
+   *   designProperties: {},
+   *   dimensionKeyMap: { designProperties: {} },
+   * });
    * ```
    */
   create(

test/unit/adapters/REST/endpoints/experience.test.ts

@@ -251,6 +251,55 @@ describe('Rest Experience', { concurrent: true }, () => {
       })
   })
 
+  test('create sends templateId when creating a template-backed experience', async () => {
+    const mockResponse = {
+      sys: { id: 'new-experience-456', type: 'Experience', version: 1 },
+      name: 'Template Experience',
+      description: 'A template-backed experience',
+      viewports: [],
+      contentProperties: {},
+      designProperties: {},
+      dimensionKeyMap: { designProperties: {} },
+    }
+
+    const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
+
+    return adapterMock
+      .makeRequest({
+        entityType: 'Experience',
+        action: 'create',
+        userAgent: 'mocked',
+        params: {
+          spaceId: 'space123',
+          environmentId: 'master',
+        },
+        payload: {
+          name: 'Template Experience',
+          description: 'A template-backed experience',
+          templateId: 'tmpl-789',
+          viewports: [],
+          contentProperties: {},
+          designProperties: {},
+          dimensionKeyMap: { designProperties: {} },
+        },
+      })
+      .then((r) => {
+        expect(r).to.eql(mockResponse)
+        expect(httpMock.post.mock.calls[0][0]).to.eql(
+          '/spaces/space123/environments/master/experiences',
+        )
+        expect(httpMock.post.mock.calls[0][1]).to.eql({
+          name: 'Template Experience',
+          description: 'A template-backed experience',
+          templateId: 'tmpl-789',
+          viewports: [],
+          contentProperties: {},
+          designProperties: {},
+          dimensionKeyMap: { designProperties: {} },
+        })
+      })
+  })
+
   test('update calls correct URL with version header', async () => {
     const mockResponse = {
       sys: { id: 'experience123', type: 'Experience', version: 2 },
@@ -301,6 +350,57 @@ describe('Rest Experience', { concurrent: true }, () => {
       })
   })
 
+  test('update sends templateId when experience is template-backed', async () => {
+    const mockResponse = {
+      sys: { id: 'experience123', type: 'Experience', version: 2 },
+      name: 'Updated Experience',
+      description: 'A template-backed experience',
+      viewports: [],
+      contentProperties: {},
+      designProperties: {},
+      dimensionKeyMap: { designProperties: {} },
+    }
+
+    const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: mockResponse }))
+
+    return adapterMock
+      .makeRequest({
+        entityType: 'Experience',
+        action: 'update',
+        userAgent: 'mocked',
+        params: {
+          spaceId: 'space123',
+          environmentId: 'master',
+          experienceId: 'experience123',
+        },
+        payload: {
+          sys: {
+            version: 1,
+            template: {
+              sys: { type: 'Link', linkType: 'Template', id: 'tmpl-456' },
+            },
+          },
+          name: 'Updated Experience',
+          description: 'A template-backed experience',
+          viewports: [],
+          contentProperties: {},
+          designProperties: {},
+          dimensionKeyMap: { designProperties: {} },
+        },
+      })
+      .then((r) => {
+        expect(r).to.eql(mockResponse)
+        expect(httpMock.put.mock.calls[0][0]).to.eql(
+          '/spaces/space123/environments/master/experiences/experience123',
+        )
+        expect(httpMock.put.mock.calls[0][2].headers['X-Contentful-Version']).to.eql(1)
+        const body = httpMock.put.mock.calls[0][1]
+        expect(body.templateId).to.eql('tmpl-456')
+        expect(body.componentTypeId).to.be.undefined
+        expect(body.sys).to.be.undefined
+      })
+  })
+
   test('delete calls correct URL', async () => {
     const { httpMock, adapterMock } = setupRestAdapter(Promise.resolve({ data: {} }))