✨ SSI: Programmatic API, E2E tests, and documentation (Phase 6)

[mormubis]

Motivation

Phase 6 of the SSI (Server-Side Instrumentation) CDN bundle generator project. This adds the programmatic API so build tools (webpack, Vite, Node.js scripts) can integrate the bundle generator directly, adds E2E tests proving the embedded config approach works, creates documentation, and extracts remote configuration into a standalone package with architectural improvements.

Builds on Phase 5 (Core Generator) which implemented the CLI tool and library for generating bundled SDK + config.

Changes

Wave 1: Programmatic API + SDK Caching

• generateBundle() API — high-level async function that orchestrates fetch config → download SDK → generate bundle with full input validation
• In-memory SDK cache in downloadSDK() — avoids re-fetching the same SDK variant during watch mode (<5ms cache hit vs ~500ms network)
• Renamed GenerateBundleOptions → CombineBundleOptions (low-level) + new GenerateBundleOptions (high-level API)
• 13 new unit tests: 8 validation + 5 cache behavior

Wave 2: E2E Tests

• embeddedConfig.scenario.ts — 8 tests: SDK loads with embedded config, rum-slim variant, no remote config requests, bundle validation
• embeddedConfigDynamic.scenario.ts — 7 tests: dynamic value markers (cookie, DOM, JS path) preserved in bundle, mixed static/dynamic values

Wave 3: Documentation

• Enhanced JSDoc on all exports with @internal, @example, @throws
• bundleGenerator.README.md — API reference, build tool integration examples (Node.js, webpack, Vite), troubleshooting

Wave 4: Review Fixes

• Fix SDK cache key — include datacenter in cache key to prevent cross-region cache hits
• Fix non-null assertion — replace configResult.value! with proper discriminated union return type
• Restore type safety — use RemoteConfiguration type instead of unknown in E2E test framework
• Add config fetch timeout — 30s timeout via Promise.race to prevent hanging builds
• Fix as any assertion — replace with targeted type assertion in buildEndpoint
• Fix ~30 lint errors — unused imports, JSDoc ordering, guard-for-in, string concat

Wave 5: Architecture Improvements

@datadog/browser-core

• buildSiteHost(site?) extraction — new lightweight function for site-to-host resolution without requiring full InitConfiguration. buildEndpointHost delegates to it for the common case.

@datadog/browser-remote-config

• RemoteConfigResult discriminated union — { ok: true; value } | { ok: false; error } for proper TypeScript narrowing (eliminates non-null assertions across all consumers)
• AbortSignal support — fetchRemoteConfiguration now accepts optional signal for request cancellation and timeouts
• buildSiteHost decoupling — uses the new buildSiteHost instead of buildEndpointHost, removing the type assertion hack

New: @datadog/browser-sdk-endpoint

• Extracted generateBundle() API into a proper published Node.js package
• Split into bundleGenerator.ts (orchestration) and sdkDownloader.ts (CDN download + caching) for single-responsibility
• Normal import of @datadog/browser-remote-config (no more dynamic import workaround)
• Uses AbortSignal.timeout(30_000) for config fetch (clean cancellation)
• CLI (generate-cdn-bundle.ts) rewired to import from the new package
• Old scripts/build/lib/bundleGenerator.ts deleted

New Packages

@datadog/browser-sdk-endpoint

Node.js package for build-time SDK bundle generation with embedded remote configuration.

import { generateBundle } from '@datadog/browser-sdk-endpoint'

const bundle = await generateBundle({
  applicationId: 'your-app-id',
  remoteConfigurationId: 'your-config-id',
  variant: 'rum'
})

Public API:

• generateBundle(options) — high-level orchestrator
• fetchConfig(options) — fetch remote configuration (with 30s timeout)
• downloadSDK(options) — download SDK from CDN (with caching)
• generateCombinedBundle(options) — combine SDK + config into IIFE bundle
• clearSdkCache() — testing utility

Test instructions

# Unit tests (browser-core endpointBuilder)
yarn test:unit --spec packages/core/src/domain/configuration/endpointBuilder.spec.ts

# Unit tests (remote-config)
yarn test:unit --spec packages/remote-config/src/remoteConfiguration.spec.ts

# Script tests (endpoint package + CLI)
yarn test:script

# E2E tests (embedded config)
yarn test:e2e -g "embedded configuration"

# Type checking
yarn typecheck

Checklist

• Tested locally
• Tested on staging
• Added unit tests for this change.
• Added e2e/integration tests for this change.
• Updated documentation and/or relevant AGENTS.md file

🤖 Generated with Claude Code

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[cit-pr-commenter-54b7da]

Bundles Sizes Evolution

📦 Bundle Name	Base Size	Local Size	𝚫	𝚫%	Status
Rum	172.21 KiB	167.46 KiB	-4.76 KiB	-2.76%	✅
Rum Profiler	4.71 KiB	4.71 KiB	0 B	0.00%	✅
Rum Recorder	24.88 KiB	24.88 KiB	0 B	0.00%	✅
Logs	56.29 KiB	56.30 KiB	+7 B	+0.01%	✅
Flagging	944 B	944 B	0 B	0.00%	✅
Rum Slim	127.99 KiB	123.33 KiB	-4.65 KiB	-3.64%	✅
Worker	23.63 KiB	23.63 KiB	0 B	0.00%	✅

🚀 CPU Performance

Action Name	Base CPU Time (ms)	Local CPU Time (ms)	𝚫%
addglobalcontext	N/A	0.0043	N/A
addaction	N/A	0.0145	N/A
adderror	N/A	0.014	N/A
addtiming	N/A	0.0029	N/A
startview	N/A	0.0136	N/A
startstopsessionreplayrecording	N/A	0.0007	N/A
logmessage	N/A	0.0168	N/A

🧠 Memory Performance

Action Name	Base Memory Consumption	Local Memory Consumption	𝚫
addglobalcontext	N/A	26.19 KiB	N/A
addaction	N/A	49.06 KiB	N/A
addtiming	N/A	26.22 KiB	N/A
adderror	N/A	55.25 KiB	N/A
startstopsessionreplayrecording	N/A	26.24 KiB	N/A
startview	N/A	448.50 KiB	N/A
logmessage	N/A	44.90 KiB	N/A

🔗 RealWorld

[datadog-datadog-prod-us1]

✅ Tests

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 76.00%
• Overall Coverage: 77.16% (-0.03%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: f44d55f | Docs | Datadog PR Page | Was this helpful? Give us feedback!}