@sonata-innovations/messaging-shared

Shared, framework-agnostic utilities for the Sonata messaging group. The home for small helpers that more than one messaging surface must run identically — so behaviour can't drift between, say, the portal's authoring preview and the customer SDK's render.

This package deliberately holds only group-shared, domain-neutral utilities. It is not a Fiber package (that's @sonata-innovations/fiber-shared, scoped to the Fiber form schema). Anything Fiber-specific belongs there, not here.

Exports

resolveEmbedded(base, overrides)

Sparse deep-merge of an embedded-overrides object over a base. Built for BRIEF-2026-06-24-002 Phase 3 (Option C): an experience is authored once, plus an optional sparse experience.embedded override block; the resolved experience is resolveEmbedded(base, embedded).

The whole reason this lives in a shared package: the authoring preview (admin-portal-frontend) and the render path (sonata-messaging-websdk) MUST apply the exact same merge, or what an author previews won't match what a customer sees. One impl, two consumers, no drift.

Behaviour:

• empty/absent overrides → returns base unchanged (zero-copy fast path)
• override scalar leaf → replaces base leaf
• override null → explicitly clears the base value to null
• override nested object → recurses
• override array → replaces atomically (not element-wise)
• override missing key → base value passes through

Validation (AJV at persistence), type coercion (TS at compile), and migration are explicitly out of scope.

Consumers

• sonata-messaging-admin-portal-frontend — authoring preview (EmbeddedOverridesPanel)
• sonata-messaging-websdk — render path (fbre-app/main.tsx), pending adoption

Provenance / status

Source extracted verbatim from the PM-verified handoff for 24-002 (impl + DeepPartialNullable + 20-assertion contract test). PM (cross-project-messaging) pre-staged this skeleton so publishing is a single step once npm publish access to the @sonata-innovations org is granted.

Open decisions for the owner (Oliver):

• npm publish access / org membership or automation token
• where the canonical repo + release CI live
• publishConfig.access: defaults to public here to match fiber-shared; flip to restricted if the group wants this internal-only (org plan permitting)

Publish (CI-on-tag, matching org norm)

prepublishOnly builds + tests before any publish. Intended flow: tag v1.0.0 → CI runs npm ci && npm run build && npm test && npm publish. See .github/workflows/publish.yml (sketch).