feat: support templateId in CreateExperienceProps for template-backed experiences [DX-982] (#3006)

* feat: support templateId in CreateExperienceProps discriminated union [DX-982]

* fix: pass templateId in update adapter for template-backed experiences [DX-982]

* test: add templateId create/update tests and update plain client JSDoc [DX-982]

* chore: prettier

Author: tylerpina

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/entities/experience.ts

@@ -72,10 +72,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: {} }))