fix(swift): add contentful.swift Entry adapter for OptimizedEntry [NT-3808]

documentation/internal/sdk-knowledge/native/ios.md

@@ -28,15 +28,16 @@ lifecycle, SwiftUI views, and preview-panel UI. Swift source root:
 Single module: `import ContentfulOptimization`. There is one SDK; both guides consume it — SwiftUI
 apps mostly use the view surface, UIKit apps mostly use the imperative `OptimizationClient` surface.
 
-| Import path (`ContentfulOptimization`) | Public symbol or purpose                                                                                                                                                      | source                                                                                                                                                                                                                                                                                     |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| SwiftUI surface                        | `OptimizationRoot`, `OptimizedEntry`, `OptimizationScrollView`, `.trackScreen(name:)` / `ScreenTrackingModifier`, `TrackingConfig`, `ScrollContext`                           | extern:SwiftUI views/modifiers — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Views/OptimizationRoot.swift#OptimizationRoot; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Views/ScreenTrackingModifier.swift#trackScreen                |
-| Imperative client                      | `OptimizationClient` (`@MainActor` `ObservableObject`); `EventEmissionResult`                                                                                                 | extern:OptimizationClient is a @MainActor ObservableObject facade wrapping the JS bridge — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationClient.swift#OptimizationClient                                                                             |
-| Config                                 | `OptimizationConfig`, `OptimizationApiConfig`, `StorageDefaults`, `OptimizationLogLevel`, `QueuePolicy`, `QueueFlushPolicy`, `QueueEvent`/`QueueEventType`, `BlockedEvent`    | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationConfig.swift#OptimizationConfig; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationConfig.swift#StorageDefaults                                        |
-| Event payloads                         | `IdentifyPayload`, `PageEventPayload`, `ScreenEventPayload`, `TrackEventPayload`, `TrackViewPayload`, `TrackClickPayload`                                                     | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/EventPayloads.swift#ScreenEventPayload; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/TrackViewPayload.swift#TrackViewPayload                                              |
-| State / result types                   | `OptimizationState`, `ResolvedOptimizedEntry`, `PreviewState` (+ DTOs), `JSONValue`, `OptimizationError`                                                                      | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationState.swift#OptimizationState; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationError.swift#OptimizationError                                         |
-| Tracking (imperative)                  | `ViewTrackingController`, `TrackingMetadata`                                                                                                                                  | extern:ViewTrackingController is a @MainActor imperative view-timing engine for UIKit — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Tracking/ViewTrackingController.swift#ViewTrackingController                                                                    |
-| Preview panel                          | `PreviewPanelOverlay` (SwiftUI), `PreviewPanelViewController` (UIKit), `PreviewPanelConfig`, `PreviewContentfulClient` / `ContentfulHTTPPreviewClient`, `PreviewPanelContent` | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Preview/PreviewPanelViewController.swift#PreviewPanelViewController; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Preview/PreviewContentfulClient.swift#ContentfulHTTPPreviewClient |
+| Import path (`ContentfulOptimization`) | Public symbol or purpose                                                                                                                                                      | source                                                                                                                                                                                                                                                                                                                                                                                           |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SwiftUI surface                        | `OptimizationRoot`, `OptimizedEntry`, `OptimizationScrollView`, `.trackScreen(name:)` / `ScreenTrackingModifier`, `TrackingConfig`, `ScrollContext`                           | extern:SwiftUI views/modifiers — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Views/OptimizationRoot.swift#OptimizationRoot; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Views/ScreenTrackingModifier.swift#trackScreen                                                                                                                      |
+| Imperative client                      | `OptimizationClient` (`@MainActor` `ObservableObject`); `EventEmissionResult`                                                                                                 | extern:OptimizationClient is a @MainActor ObservableObject facade wrapping the JS bridge — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationClient.swift#OptimizationClient                                                                                                                                                                                   |
+| Config                                 | `OptimizationConfig`, `OptimizationApiConfig`, `StorageDefaults`, `OptimizationLogLevel`, `QueuePolicy`, `QueueFlushPolicy`, `QueueEvent`/`QueueEventType`, `BlockedEvent`    | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationConfig.swift#OptimizationConfig; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationConfig.swift#StorageDefaults                                                                                                                                              |
+| Event payloads                         | `IdentifyPayload`, `PageEventPayload`, `ScreenEventPayload`, `TrackEventPayload`, `TrackViewPayload`, `TrackClickPayload`                                                     | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/EventPayloads.swift#ScreenEventPayload; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/TrackViewPayload.swift#TrackViewPayload                                                                                                                                                    |
+| State / result types                   | `OptimizationState`, `ResolvedOptimizedEntry`, `ResolvedContentfulOptimizedEntry`, `PreviewState` (+ DTOs), `JSONValue`, `OptimizationError`                                  | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationState.swift#OptimizationState; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/ResolvedOptimizedEntry.swift#ResolvedContentfulOptimizedEntry; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationError.swift#OptimizationError |
+| `contentful.swift` adapter             | `OptimizationEntryMapping.toOptimizationEntry(_:)` (`Contentful.Entry` → `[String: Any]`); `ResolvedEntry`                                                                    | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Contentful/OptimizationEntryMapping.swift#OptimizationEntryMapping; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Contentful/ResolvedEntry.swift#ResolvedEntry                                                                                                                             |
+| Tracking (imperative)                  | `ViewTrackingController`, `TrackingMetadata`                                                                                                                                  | extern:ViewTrackingController is a @MainActor imperative view-timing engine for UIKit — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Tracking/ViewTrackingController.swift#ViewTrackingController                                                                                                                                                                          |
+| Preview panel                          | `PreviewPanelOverlay` (SwiftUI), `PreviewPanelViewController` (UIKit), `PreviewPanelConfig`, `PreviewContentfulClient` / `ContentfulHTTPPreviewClient`, `PreviewPanelContent` | extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Preview/PreviewPanelViewController.swift#PreviewPanelViewController; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Preview/PreviewContentfulClient.swift#ContentfulHTTPPreviewClient                                                                                                       |
 
 - SPM target links `JavaScriptCore` for consuming apps and copies `optimization-ios-bridge.umd.js`
   as a package resource; platforms are iOS 15+ / macOS 12+. source: extern:Package.swift links JavaScriptCore and copies the UMD bundle resource, iOS 15/macOS 12 — packages/ios/ContentfulOptimization/Package.swift
@@ -152,6 +153,31 @@ viewportHeight:)` from its own scroll/layout callbacks and the controller applie
   expanded inline `nt_mergetag` entry to the bridge, which reads the selector against the current
   profile and returns the resolved string or `nil` (fallback). The app owns extracting the embedded
   entry from Rich Text before calling it. source: extern:getMergeTagValue passes the mergetag entry to the bridge — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationClient.swift#OptimizationClient; core-sdk#resolvers/MergeTagValueResolver.ts#resolve; kb:shared/concepts.md
+- `contentful.swift` integration: `OptimizationEntryMapping.toOptimizationEntry(_:)` converts a
+  `Contentful.Entry` into the `{sys, fields, metadata}` map the resolver expects, recursively
+  expanding resolved links/assets/rich text and always emitting `metadata: {tags, concepts}` (empty
+  when absent) so the resolver's entry guard never silently treats a real optimized entry as
+  non-optimized. `OptimizedEntry(entry: Contentful.Entry, ...)` is a second SwiftUI initializer that
+  runs the map once at construction and hands the resolved variant back through `ResolvedEntry`
+  instead of a raw dict; both initializers produce the same `OptimizedEntry<Content>` type.
+  source: extern:OptimizationEntryMapping.toOptimizationEntry always emits metadata, recurses links/rich text — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Contentful/OptimizationEntryMapping.swift#OptimizationEntryMapping; extern:OptimizedEntry(entry: Contentful.Entry) initializer wraps the mapping and ResolvedEntry — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Views/OptimizedEntry.swift#OptimizedEntry
+- The imperative UIKit path has the same `Contentful.Entry` overload as the SwiftUI view:
+  `OptimizationClient.resolveOptimizedEntry(baseline: Contentful.Entry, selectedOptimizations:)`
+  maps `baseline` through `OptimizationEntryMapping` once, then delegates to the dict-based
+  overload and wraps its result in `ResolvedContentfulOptimizedEntry` (`entry: ResolvedEntry`
+  instead of a raw dict). It inherits the dict-based overload's fail-soft behavior exactly — not
+  initialized, a serialization error, or an unparseable bridge result all fall back to the mapped
+  baseline with `selectedOptimization`/`optimizationContextId` nil.
+  source: extern:OptimizationClient.resolveOptimizedEntry(baseline: Contentful.Entry) maps then delegates to the dict overload — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationClient.swift#OptimizationClient; extern:packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/ResolvedOptimizedEntry.swift#ResolvedContentfulOptimizedEntry
+- `ResolvedEntry` mirrors `Contentful.Entry`'s own readable surface — `id`, `localeCode`,
+  `createdAt`, `updatedAt`, `getField<T>(_:)`, and the `String`/`Int` convenience subscripts — so a
+  resolved variant reads exactly like a fetched `Entry` instead of a raw map. It does **not** mirror
+  `Entry.type`/`currentlySelectedLocale`/`metadata`/`setLocale(withCode:)`: `type: ContentType?` and
+  `currentlySelectedLocale: Locale` are full fetched resources the resolved map never carries and
+  `contentful.swift` gives no public initializer to fabricate, and `Metadata` has no public
+  initializer either, so `metadata.tags` on the resolved map can only be read via `getField`, never
+  wrapped back into a real `Metadata` value.
+  source: extern:ResolvedEntry mirrors Entry.id/localeCode/createdAt/updatedAt/getField/subscripts, omits type/currentlySelectedLocale/metadata/setLocale by design — packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Contentful/ResolvedEntry.swift#ResolvedEntry
 
 ## Identifier ownership
 

implementations/ios-sdk/uikit/Components/OptimizedEntryUIView.swift

@@ -107,7 +107,7 @@ final class OptimizedEntryUIView: UIView {
                 baseline: entry,
                 selectedOptimizations: effectiveOptimizations
             )
-            resolvedEntry = result.entry
+            resolvedEntry = result.entry.toDictionary(fallback: entry)
             resolvedOptimization = result.selectedOptimization
         } else {
             resolvedEntry = entry

packages/ios/ContentfulOptimization/Package.swift

@@ -2,7 +2,7 @@
 
 import PackageDescription
 
-let package = Package(
+let package: Package = Package(
     name: "ContentfulOptimization",
     platforms: [.iOS(.v15), .macOS(.v12)],
     products: [
@@ -11,9 +11,15 @@ let package = Package(
             targets: ["ContentfulOptimization"]
         ),
     ],
+    dependencies: [
+        .package(url: "https://github.com/contentful/contentful.swift", exact: "5.5.15"),
+    ],
     targets: [
         .target(
             name: "ContentfulOptimization",
+            dependencies: [
+                .product(name: "Contentful", package: "contentful.swift"),
+            ],
             resources: [
                 .copy("Resources/optimization-ios-bridge.umd.js"),
             ],
@@ -23,7 +29,10 @@ let package = Package(
         ),
         .testTarget(
             name: "ContentfulOptimizationTests",
-            dependencies: ["ContentfulOptimization"]
+            dependencies: [
+                "ContentfulOptimization",
+                .product(name: "Contentful", package: "contentful.swift"),
+            ]
         ),
     ]
 )