feat(exo): support viewport-free exo responses [SPA-5371]

[Thomas Kellermeier (Chaoste)]

Summary

Allow ExO entity responses without the deprecated viewports field.

Description

Updates the public types for both the legacy and renamed ExO entities so API responses that omit viewports type-check. Adds a type-level regression test covering every affected response type.

Motivation and Context

SPA-5371 coordinates clients ahead of the API response change that removes viewports. Without this relaxation, consumers cannot parse the post-migration response shape.

PR Checklist

• I have read the CONTRIBUTING.md file
• All commits follow conventional commits
• Documentation is updated (if necessary)
• PR doesn't contain any sensitive information
• There are no breaking changes

Note: This PR was created with the contentful-github-create-pull-request skill, powered by Agents Kit. To follow or use this workflow, see the Agents Kit CLI skill docs.

Summary by Bito

This PR updates the public ExO TypeScript entity models to accept API responses that omit the deprecated viewports field. It also broadens designProperties for experience and fragment entities to accept both flattened and dimensioned values, with compile-time regression coverage for the affected current and legacy types.

Detailed Changes

• Makes viewports optional in ComponentProps, ComponentTypeProps, TemplateProps, ExperienceTemplateProps, ExperienceProps, ExperienceFragmentProps, and FragmentProps in component.ts, component-type.ts, experience-template.ts, experience.ts, experience-fragment.ts, fragment.ts, and template.ts.
• Introduces EntityDesignProperties in component-type.ts as a record whose values can be direct DesignPropertyValue instances or dimensioned design-property records.
• Applies EntityDesignProperties to experience and fragment entity models and their inline fragment nodes in experience.ts, experience-fragment.ts, and fragment.ts, preserving support for existing dimensioned values while accepting flattened API values.
• Adds compile-time assertions in exo.test-d.ts covering optional viewports and EntityDesignProperties across current and legacy entity and inline-node types.

[bito-code-review]

Changelist by Bito

This pull request implements the following key changes.

Key Change	Files Impacted	Summary
Feature Improvement - Support ExO Responses Without Viewports	component-type.ts, component.ts, experience-template.ts, experience.ts, experience-fragment.ts, fragment.ts, template.ts	Makes the deprecated viewports property optional across current and legacy ExO entity prop types, allowing API responses that omit the field to type-check.
Feature Improvement - Broaden ExO Design Property Types	component-type.ts, experience.ts, experience-fragment.ts, fragment.ts, exo.test-d.ts	Adds EntityDesignProperties to support both direct design-property values and dimensioned values for experience, fragment, and inline fragment entities, with compile-time regression coverage.

[bito-code-review]

Functional Validation by Bito

Source	Requirement / Code Area	Status	Notes
SPA-5371, SPA-5269, Viewport-Removal-Client-Migration	Update affected ExO clients and public types so responses without the deprecated viewports field are accepted.	✅ Met	The public ExO entity types now make viewports optional across lib/entities/component-type.ts, lib/entities/component.ts, lib/entities/experience.ts, lib/entities/experience-fragment.ts, lib/entities/experience-template.ts, lib/entities/fragment.ts, and lib/entities/template.ts. Type-level coverage in lib/entities/exo.test-d.ts verifies that responses without the deprecated field are accepted.
SPA-5371, Viewport-Removal-Client-Migration	Allow ExO value-side payloads without viewports to use flattened design-property values while continuing to support dimensioned design-property values when viewports are present.	✅ Met	The new EntityDesignProperties type in lib/entities/component-type.ts allows each design-property entry to be either a flattened DesignPropertyValue or a dimensioned DimensionedDesignPropertyValue. Experience, Experience Fragment, Fragment, and inline node types use this shared type, and lib/entities/exo.test-d.ts verifies the updated value-side shapes.
SPA-5371, Viewport-Removal-Client-Migration	Ensure read-modify-write flows preserve the matching viewports and design-property value shape, and do not replace an omitted viewports field with an empty array.	🟡 Partial	The type changes preserve compatibility with both optional viewports and dimensioned design-property values when viewports are present, but the diff contains no read-modify-write implementation or behavioral tests proving that matching shapes are preserved or that an omitted viewports field is not replaced with an empty array. Existing fixtures in the repository still contain empty viewport arrays, so the required migration behavior cannot be confirmed.

[bito-code-review]

Impact Analysis by Bito

Interaction Diagram

sequenceDiagram
participant Consumer as SDK Consumer
participant Client as Plain Client
participant Types as Entity Types<br/>🔄 Updated | ●●● High
participant API as Contentful API
participant RefTree as 🔗 Reference Tree (experience-packages)
participant Tests as Type Contract Tests<br/>🟩 Added | ●●○ Medium
Consumer->>Client: Request experience or fragment data
Client->>API: GET ExO entity endpoint
API-->>Client: Return entity response
Client->>Types: Apply updated entity response types
Types-->>Client: Accept optional viewports and flattened properties
Client-->>Consumer: Return typed entity data
Consumer->>Types: Compile against EntityDesignProperties
Types->>Tests: Validate entity property contracts
Tests-->>Types: Confirm absent viewports are supported
Consumer->>RefTree: Pass typed entity design properties
RefTree->>Types: Resolve shared entity property types
Types-->>RefTree: Provide compatible flattened property values
alt response includes deprecated viewports
API-->>Client: Include viewport collection when present
Client-->>Consumer: Expose optional viewport data
else response omits deprecated viewports
API-->>Client: Return flattened design properties only
Client-->>Consumer: Expose the new compatible shape
    end
Consumer-->>RefTree: Render or process the typed entity tree

Loading

---

This MR updates the entity type transformation contract by adding EntityDesignProperties and making deprecated viewports optional across ExO entities, while adding type-level contract tests. The Plain Client still integrates with the Contentful API, and the downstream Reference Tree package can consume responses with flattened design properties or without viewports. The main upstream impact is on SDK consumers that compile against these exported types, with no runtime persistence changes.

Cross-Repository Impact Analysis

What Changed	Impact of Change	Suggested Review Actions
The SDK now makes viewports optional across ComponentType, Component, Experience, ExperienceFragment, ExperienceTemplate, Fragment, and Template props, and widens designProperties for Experience and Fragment entities to allow flattened non-dimensioned values through EntityDesignProperties.	- verify-needed: ComponentTypeProps.viewports, ComponentProps.viewports, ExperienceProps.viewports, ExperienceFragmentProps.viewports, ExperienceTemplateProps.viewports, FragmentProps.viewports, TemplateProps.viewports: The exported TypeScript contracts changed from required viewports arrays to optional properties. Consumer code that assumes viewports is always present may require runtime guards or updated narrowing. - verify-needed: ExperienceProps.designProperties, ExperienceFragmentProps.designProperties, InlineExperienceFragmentNode.designProperties, InlineFragmentNode.designProperties: The designProperties type now accepts either direct DesignPropertyValue values or dimensioned records. Consumers performing dimension-specific indexing may need additional type narrowing.	- Run organization-wide searches for the exact exported property and type names before merge. - Inspect downstream consumers for unconditional access to entity.viewports. - Inspect consumers that index designProperties twice, since flattened values may no longer support dimension-key indexing. - Publish or document the compatibility implications for TypeScript consumers.

Code Paths Analyzed

Impact:
This is a TypeScript declaration-model change for Experience Framework entities. It permits API responses without viewports and permits flattened design property values, while retaining the existing dimensioned representation.

Flow:
Management API response payloads → entity prop and inline-node type declarations → generated/public SDK typings → downstream TypeScript consumers and type-level tests.

Direct Changes (Diff Files):
• lib/entities/component-type.ts [117-123, 261-265] — Adds the exported EntityDesignProperties type and makes ComponentTypeProps.viewports optional.
• lib/entities/component.ts [45-50] — Makes ComponentProps.viewports optional.
• lib/entities/exo.test-d.ts [1-45] — Adds compile-time type assertions covering optional viewports and EntityDesignProperties across ExO entities.
• lib/entities/experience-fragment.ts [9-12, 41-49] — Replaces DimensionedDesignPropertyValue with EntityDesignProperties and makes viewports optional.
• lib/entities/experience-template.ts [42-47] — Makes ExperienceTemplateProps.viewports optional.
• lib/entities/experience.ts [8-12, 45-49, 82-89] — Uses EntityDesignProperties for Experience and inline fragment design properties and makes ExperienceProps.viewports optional.
• lib/entities/fragment.ts [1-11, 19-25, 60-68] — Uses EntityDesignProperties for legacy Fragment design properties and makes FragmentProps.viewports optional.
• lib/entities/template.ts [49-56] — Makes legacy TemplateProps.viewports optional.

Repository Impact:
• Public TypeScript entity declarations: Consumers receive different requiredness and value-shape guarantees from the SDK types.
• Experience Framework design-property handling: Experience and fragment design properties can now be represented either as direct values or dimensioned records.
• Type-level regression coverage: The new exo.test-d.ts file verifies the intended declaration shapes but does not test runtime payload transformation.

Cross-Repository Dependencies:
• External TypeScript consumers of contentful-management.js: The changed exported entity types are part of the SDK surface and may affect compilation and runtime assumptions.

Database/Caching Impact:
• None

API Contract Violations:
• Making viewports optional is source-compatible for consumers that only construct values, but may expose undefined to consumers that previously relied on the required property.
• Changing designProperties from Record<string, DimensionedDesignPropertyValue> to EntityDesignProperties broadens the accepted type and may invalidate consumers that assume every property is dimensioned.
• The diff changes TypeScript declarations only; no runtime validation or normalization is shown for payloads containing flattened design properties.

Infrastructure Dependencies:
• No database migrations, environment variables, deployment configuration, or dependency version changes are present in the diff.
• The local type-test command could not start because the installed Rolldown native binding was unavailable; this is an environment/tooling failure rather than a reported type failure.

Additional Insights:
• Backward compatibility: Legacy ComponentType, Fragment, and Template declarations remain exported and are marked deprecated, but their property contracts also change. Existing consumers of deprecated types are still affected.
• Runtime behavior: Because the changes are type-only, runtime behavior is unchanged unless downstream code changes its handling based on the new declarations.

Testing Recommendations

Frontend Impact:
• Compile representative consumers that access viewports on ComponentProps, ComponentTypeProps, ExperienceProps, ExperienceFragmentProps, ExperienceTemplateProps, FragmentProps, and TemplateProps without guards.
• Compile consumers that read designProperties as both a direct DesignPropertyValue and a dimensioned record.

Service Integration:
• Run an integration fixture for Management API responses where viewports is omitted from each affected entity type.
• Run an integration fixture for Experience and Fragment payloads containing flattened designProperties values.

Data Serialization:
• Validate serialization and deserialization of designProperties containing ManualDesignValue and DesignTokenValue directly at the property level.
• Validate that existing dimensioned designProperties payloads remain accepted after the EntityDesignProperties change.

Privacy Compliance:
• None.

Backward Compatibility:
• Run downstream TypeScript builds against the new declarations, focusing on code that assumes viewports is always defined.
• Verify that consumers using the legacy Fragment, Template, and ComponentType types still compile or receive an intentional migration notice.

OAuth Functionality:
• None

Cross-Service Communication:
• Test Management API response fixtures with missing viewports and mixed flattened/dimensioned designProperties shapes.
• Confirm no response mapper or client-side normalizer rejects the newly supported payload shapes.

Reliability Testing:
• None

Additional Insights:
• Re-run the type test command after reinstalling dependencies with the missing Rolldown optional binding restored.
• Add negative type assertions demonstrating that invalid designProperties values and invalid viewport element shapes remain rejected.

_{Analysis based on known dependency patterns and edges. Actual impact may vary.}

[bito-code-review]

Code Review Agent Run #a80e52

Actionable Suggestions - 3

• lib/entities/fragment.ts - 1

  • Undocumented exported-type change · Line 69-70
• lib/entities/experience.ts - 1

  • Exported type contract change · Line 49-50
• lib/entities/experience-fragment.ts - 1

  • Exported type change undocumented · Line 46-47

Additional Suggestions - 1

• lib/entities/experience.ts - 1

  • Duplicated inline design-property type · Line 50-50
    The inline union `Record` is repeated at lines 50 and 87 (and in `experience-fragment.ts`/`fragment.ts`). Extracting a named alias would keep the flattened-vs-dimensioned shape defined once and avoid divergence when it changes.

Review Details

• Files reviewed - 8 · Commit Range: 273e6f3..74897db

  • lib/entities/component-type.ts
  • lib/entities/component.ts
  • lib/entities/exo.test-d.ts
  • lib/entities/experience-fragment.ts
  • lib/entities/experience-template.ts
  • lib/entities/experience.ts
  • lib/entities/fragment.ts
  • lib/entities/template.ts
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

Code Review Agent Run #e7391c

Actionable Suggestions - 0

Review Details

• Files reviewed - 2 · Commit Range: 74897db..729cb25

  • lib/methods/action.ts
  • test/integration/entry-integration.test.ts
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

Code Review Agent Run #8c9434

Actionable Suggestions - 0

Review Details

• Files reviewed - 41 · Commit Range: 729cb25..93a1f54

  • lib/common-types.ts
  • lib/entities/ai-action-invocation.ts
  • lib/entities/app-action-call.ts
  • lib/entities/app-event-subscription.ts
  • lib/entities/app-installation.ts
  • lib/entities/app-signed-request.ts
  • lib/entities/app-signing-secret.ts
  • lib/entities/automation-definition.ts
  • lib/entities/automation-execution.ts
  • lib/entities/available-license.ts
  • lib/entities/bulk-action.ts
  • lib/entities/comment.ts
  • lib/entities/component-type.ts
  • lib/entities/content-semantics-index.ts
  • lib/entities/content-type.ts
  • lib/entities/data-assembly.ts
  • lib/entities/editor-interface.ts
  • lib/entities/eligible-license.ts
  • lib/entities/environment-alias.ts
  • lib/entities/oauth-application.ts
  • lib/entities/organization-invitation.ts
  • lib/entities/organization-membership.ts
  • lib/entities/personal-access-token.ts
  • lib/entities/release-action.ts
  • lib/entities/resource-provider.ts
  • lib/entities/resource-type.ts
  • lib/entities/role.ts
  • lib/entities/scheduled-action.ts
  • lib/entities/semantic-duplicates.ts
  • lib/entities/semantic-recommendations.ts
  • lib/entities/semantic-reference-suggestions.ts
  • lib/entities/semantic-settings.ts
  • lib/entities/snapshot.ts
  • lib/entities/space-add-on.ts
  • lib/entities/space-membership.ts
  • lib/entities/task.ts
  • lib/entities/team-space-membership.ts
  • lib/entities/upload-credential.ts
  • lib/entities/usage.ts
  • lib/entities/workflow-definition.ts
  • lib/entities/workflows-changelog-entry.ts
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

Code Review Agent Run #cc32fd

Actionable Suggestions - 0

Additional Suggestions - 1

• lib/entities/exo.test-d.ts - 1

  • Tautological type assertion · Line 31-39
    These assertions now compare `ExperienceProps['designProperties']` (and the sibling props) against `EntityDesignProperties` — the very alias used to declare them, imported from `../index`. The check is self-referential: if `EntityDesignProperties` is later narrowed (e.g. dropping `DimensionedDesignPropertyValue`), the test still passes. Assert against an independently written expected shape instead.

Review Details

• Files reviewed - 6 · Commit Range: 93a1f54..94db81c

  • lib/entities/component-type.ts
  • lib/entities/exo.test-d.ts
  • lib/entities/experience-fragment.ts
  • lib/entities/experience.ts
  • lib/entities/fragment.ts
  • lib/export-types.ts
• Files skipped - 1

  • MIGRATION.md - Reason: Filter setting
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

Code Review Agent Run #49cb36

Actionable Suggestions - 2

• lib/entities/fragment.ts - 1

  • Breaking type change undocumented · Line 65-65
• lib/entities/experience-fragment.ts - 1

  • CWE-1078: Inappropriate Coupling Breaking Type · Line 45-45

Additional Suggestions - 2

• lib/entities/exo.test-d.ts - 2

  • Misleading test title · Line 15-15
    The test title calls `viewports` 'deprecated', but no `@deprecated` tag exists on `viewports` in `ComponentProps`, `ComponentTypeProps`, `ExperienceProps`, `ExperienceFragmentProps`, `ExperienceTemplateProps`, `FragmentProps`, or `TemplateProps` (verified via grep across `lib/`). Either rename the test to describe optionality, or add the deprecation marker to the types if that is intended.
  • Title references untested scenario · Line 33-33
    The title says 'when viewports are absent', but the body only asserts `designProperties` types and never references `viewports`. Rename it to describe the actual assertion (e.g. 'designProperties is EntityDesignProperties') so the title does not imply coverage that does not exist.

Review Details

• Files reviewed - 8 · Commit Range: ed806d8..85c83c1

  • lib/entities/component-type.ts
  • lib/entities/component.ts
  • lib/entities/exo.test-d.ts
  • lib/entities/experience-fragment.ts
  • lib/entities/experience-template.ts
  • lib/entities/experience.ts
  • lib/entities/fragment.ts
  • lib/entities/template.ts
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[Thomas Kellermeier (Chaoste)]

Blocked by #3153, which resolves the unrelated ESLint/Prettier CI baseline errors exposed by current master. Once #3153 merges, rerun this PR’s checks.

[Lisa White (whitelisab)]

While it is technically correct that this is a breaking change to the Experiences API, we have specifically noted in the README that breaking changes can happen with Experiences since this is still "experimental" while we are pre-beta. We would prefer to not ship this as a new major release for the entire SDK. Can you remove any feat! and BREAKING CHANGE: annotations from your commits and the PR title so that we can ensure that this goes out as a new minor release? Thank you!

[bito-code-review]

Code Review Agent Run #41e6fb

Actionable Suggestions - 0

Review Details

• Files reviewed - 8 · Commit Range: a8242e0..cb6e62b

  • lib/entities/component-type.ts
  • lib/entities/component.ts
  • lib/entities/exo.test-d.ts
  • lib/entities/experience-fragment.ts
  • lib/entities/experience-template.ts
  • lib/entities/experience.ts
  • lib/entities/fragment.ts
  • lib/entities/template.ts
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by