@dynatrace/rum-javascript-sdk 1.329.3 → 1.329.4

package/AGENTS.md

@@ -1,585 +0,0 @@
-# RUM JavaScript API Development
-
-**Read the root `AGENTS.md` first** - this file contains only rum-javascript-api-specific additions.
-
-## Package Purpose
-
-Customer-facing npm package that provides **safe wrapper functions** around the Dynatrace RUM JavaScript API. This is NOT the agent implementation itself, but a convenience library customers can install via npm to:
-
-1. **Safely call RUM APIs** without checking if the agent is loaded (synchronous API).
-2. **Wait for RUM availability** with Promise-based async API.
-3. **Get TypeScript support** for RUM API types and IntelliSense.
-4. **Test RUM integration** using Playwright testing utilities.
-
-This package wraps the global `dynatrace` namespace that the actual RUM JavaScript agent provides.
-
-## API Approaches
-
-### Two Wrapper Patterns
-
-**Synchronous API (`@dynatrace/rum-javascript-api/api`)**:
-- Safe no-op wrappers that gracefully handle missing RUM JavaScript.
-- Functions execute silently if agent not loaded.
-- Recommended for most use cases (graceful degradation).
-- Example: `sendEvent()`, `identifyUser()`, `addEventModifier()`
-
-**Asynchronous API (`@dynatrace/rum-javascript-api/api/promises`)**:
-- Promise-based wrappers that wait for RUM JavaScript availability.
-- Throws `DynatraceError` if agent not available within timeout.
-- Useful for critical instrumentation or consent-based loading.
-- Same functions with async signatures and configurable timeouts.
-
-### Key Difference
-
-Both call the same underlying `dynatrace` API, but:
-- **Sync**: Returns immediately, may be no-op if agent unavailable.
-- **Async**: Waits up to timeout for agent, throws if unavailable.
-
-## API Stability
-
-**Critical Requirements**:
-- **No Breaking Changes**: Customers install this via npm and depend on stable API.
-- **Backward Compatibility**: Wrapper must work with old and new agent versions.
-- **Deprecation Process**: Warn before removal, provide migration path.
-
-## Core Wrapper Functions
-
-### Synchronous Wrappers
-
-Located in `source/api/`:
-- `sendEvent(fields, eventContext?)`: Send custom event with properties.
-- `addEventModifier(eventModifier)`: Register function to modify events before sending.
-- `runHealthCheck(config?)`: Run RUM JavaScript health diagnostics.
-- `identifyUser(value)`: Associate session with user identifier.
-- `sendSessionPropertyEvent(fields)`: Send session-level properties.
-
-**Implementation Pattern**:
-- Check if `dynatrace` namespace exists.
-- Return early (no-op) if not available.
-- Call actual RUM API function if available.
-- Return `undefined` for functions that would return values.
-
-### Asynchronous Wrappers
-
-Located in `source/api/promises/`:
-- Same function names as synchronous versions.
-- Additional `timeout` parameter (default 10,000ms).
-- Returns `Promise` that resolves when RUM API called.
-- Throws `DynatraceError` if timeout exceeded.
-
-**Implementation Pattern**:
-- Register property listener for `dynatrace` namespace availability.
-- Wait up to timeout milliseconds.
-- Call namespace function once available.
-- Throw error if timeout reached without availability.
-
-## Type Definitions
-
-### Type Exports
-
-### Global Type Augmentation
-
-Types exported from `@dynatrace/rum-javascript-api/types`.
-Package provides global `window.dynatrace` type augmentation:
-- Automatically available when package installed.
-- No import needed for `window.dynatrace` IntelliSense.
-- Type inference works out-of-the-box.
-
-### TypeScript Configuration
-
-Add to `tsconfig.json` under `compilerOptions`:
-```json
-"typeRoots": ["./node_modules/@types", "./node_modules/@dynatrace/"]
-```
-
-**Reference**: `types.md` for detailed type usage examples and integration guide.
-
-### Type Safety for Customers
-
-- Full TypeScript IntelliSense support for wrapper functions.
-- Global `window.dynatrace` namespace typed automatically.
-- Compile-time validation of event property names.
-- Catch API usage errors before runtime.
-
-## Testing Framework
-
-### Playwright Test Utilities
-
-Exported from `@dynatrace/rum-javascript-api/test`:
-- **Purpose**: Test RUM integration in Playwright end-to-end tests.
-- **Functionality**: Wait for and validate RUM events and beacons in automated tests.
-- **Use Cases**: Assert on event properties, validate beacon sending, test RUM workflows.
-
-**Reference**: `testing.md` for complete API documentation and examples.
-
-### Setup Requirements
-
-**Dynatrace Configuration** needed for testing:
-1. **Access Token**: Create token with `Read RUM manual insertion tags` permission (API V2 scope).
-2. **Environment URL**: Dynatrace API endpoint (e.g., `https://{env-id}.live.dynatrace.com`).
-3. **Application ID**: Frontend application ID (e.g., `APPLICATION-ABCDEF0123456789`).
-
-Configure in Playwright test:
-```typescript
-import { test } from "@dynatrace/rum-javascript-api/test";
-
-test.use({
-    dynatraceConfig: {
-        appId: process.env.DT_APP_ID!,
-        token: process.env.DT_TOKEN!,
-        endpointUrl: process.env.DT_ENDPOINT_URL!
-    }
-});
-```
-
-### DynatraceTesting Fixture API
-
-**`waitForBeacons(options?)`**: Wait for beacon requests.
-- `minCount`: Minimum number of beacons to wait for.
-- `timeout`: Maximum wait time (default: 30,000ms).
-- Returns: `Promise<BeaconRequest[]>`
-
-**`expectToHaveSentEvent(event, options?)`**: Assert specific event sent.
-- `event`: Event object to match (uses Playwright's `toMatchObject`).
-- `timeout`: Maximum wait time (default: 30,000ms).
-- Returns: `Promise<void>`
-
-**`expectToHaveSentEventTimes(event, times, options?)`**: Assert event sent N times.
-- `event`: Event object to match.
-- `times`: Expected number of times event sent.
-- `timeout`: Maximum wait time (default: 30,000ms).
-- Returns: `Promise<void>`
-
-**`clearEvents()`**: Clear all events and beacons.
-- Resets event tracking for subsequent assertions.
-- Useful for testing multiple scenarios in one test.
-
-### Testing Patterns
-
-**Basic Event Assertion**:
-```typescript
-test("sends custom event", async ({ page, dynatraceTesting }) => {
-    await page.goto("http://localhost:3000");
-    await page.getByText("Submit").click();
-    
-    await dynatraceTesting.expectToHaveSentEvent({
-        "event_properties.action": "submit"
-    });
-});
-```
-
-**Multiple Event Assertions**:
-```typescript
-test("sends event multiple times", async ({ page, dynatraceTesting }) => {
-    await page.goto("http://localhost:3000");
-    
-    // Click button 3 times
-    for (let i = 0; i < 3; i++) {
-        await page.getByText("Add").click();
-    }
-    
-    await dynatraceTesting.expectToHaveSentEventTimes({
-        "event_properties.button": "add"
-    }, 3);
-});
-```
-
-**Testing with Event Clearing**:
-```typescript
-test("test scenarios separately", async ({ page, dynatraceTesting }) => {
-    // First scenario
-    await page.goto("http://localhost:3000");
-    await dynatraceTesting.expectToHaveSentEvent({
-        "event_properties.page": "home"
-    });
-    
-    // Clear and test second scenario
-    dynatraceTesting.clearEvents();
-    await page.goto("http://localhost:3000/about");
-    await dynatraceTesting.expectToHaveSentEvent({
-        "event_properties.page": "about"
-    });
-});
-```
-
-### Routing Considerations
-
-**Important**: Testing fixture registers asterisk route `"**"` to inject RUM JavaScript.
-- May interfere with existing Playwright routing rules.
-- Order of fixture destructuring matters.
-- Be aware of potential route conflicts in tests.
-
-**Reference**: `testing.md` troubleshooting section for routing issues.
-
-## Event Property Naming
-
-### Required Prefixes
-
-**Custom Event Properties**:
-- Must be prefixed with `event_properties.`
-- Properties without prefix are ignored by agent.
-- Naming: lowercase, numbers, underscores, dots only.
-
-**Session Properties**:
-- Must be prefixed with `session_properties.`
-- Same naming conventions as event properties.
-
-### Valid Examples
-
-```typescript
-// ✅ Correct event properties
-sendEvent({
-  'event_properties.action': 'login',
-  'event_properties.method': 'oauth',
-  'event_properties.page_name': 'dashboard'
-});
-
-// ✅ Correct session properties
-sendSessionPropertyEvent({
-  'session_properties.user_type': 'premium',
-  'session_properties.region': 'us_east'
-});
-
-// ❌ Wrong - missing prefix
-sendEvent({
-  'action': 'login',  // Will be ignored
-  'method': 'oauth'   // Will be ignored
-});
-```
-
-## Documentation
-
-### Customer-Facing Documentation
-
-**README.md** (Primary documentation):
-- Installation instructions via npm.
-- Quick start examples for sync and async APIs.
-- Complete API reference for all wrapper functions.
-- Error handling patterns and `DynatraceError` usage.
-- Best practices: when to use sync vs async.
-- Event property naming conventions.
-- Common integration patterns.
-
-**types.md** (TypeScript integration guide):
-- TypeScript configuration setup (`typeRoots`).
-- Type inference examples for `window.dynatrace`.
-- Importing specific types from package.
-- Global type augmentation explanation.
-- Usage examples with type safety.
-
-**testing.md** (Playwright testing framework):
-- Setup instructions: access token, environment URL, app ID.
-- `DynatraceTesting` fixture API reference.
-- Test configuration with `test.use()`.
-- Event assertion methods with examples.
-- Troubleshooting: routing conflicts, beacon delays.
-- Complete testing patterns and best practices.
-
-### JSDoc Requirements
-
-Every exported function must have:
-- Clear description of purpose and behavior.
-- Parameter documentation with types.
-- Return value description.
-- Usage examples via `@example` tag.
-- Notes about RUM JavaScript availability handling.
-
-## Wrapper Design Principles
-
-### Safe Defaults
-
-**Synchronous API Philosophy**:
-- Fail silently if RUM JavaScript unavailable.
-- Never throw errors that break customer code.
-- Graceful degradation for missing agent.
-- No runtime overhead checking availability.
-
-**Asynchronous API Philosophy**:
-- Explicitly handle agent availability.
-- Timeout to prevent infinite waiting.
-- Clear error when agent unavailable.
-- Used when reliability is critical.
-
-### Minimal Overhead
-
-- Wrapper functions are thin shims.
-- No data transformation or validation.
-- Direct pass-through to underlying API.
-- Negligible performance impact.
-
-### TypeScript First
-
-- All functions have complete type definitions.
-- Types match underlying RUM API exactly.
-- IntelliSense support for all methods.
-- Compile-time safety for customers.
-
-## Testing
-
-### Unit Tests (Vitest)
-
-Run: `pnpm test` with coverage.
-
-**Test Coverage**:
-- Synchronous wrappers handle missing `dynatrace`.
-- Asynchronous wrappers wait and timeout correctly.
-- `DynatraceError` thrown at correct times.
-- Type definitions compile correctly.
-- Event modifiers return unsubscribers.
-
-**Mock Strategy**:
-- Mock global `dynatrace` namespace.
-- Test both presence and absence scenarios.
-- Verify correct underlying API called.
-- Test timeout behavior for async wrappers.
-
-### Testing Applications Using This Package
-
-**Playwright Test Fixtures**:
-- Use testing utilities from `@dynatrace/rum-javascript-api/test`.
-- Wait for RUM events in test assertions.
-- Validate event properties sent correctly.
-- Test RUM integration without mocking.
-
-**Reference**: `testing.md` for complete testing framework documentation.
-
-## Relationship to RUM JavaScript Agent
-
-### Wrapper vs Implementation
-
-**This package (`@dynatrace/rum-javascript-api`)**:
-- npm package customers install in their applications.
-- Provides safe wrapper functions around global `dynatrace` API.
-- Adds TypeScript types and convenience methods.
-- Independent of agent loading mechanism.
-
-**RUM JavaScript Agent**:
-- Injected script that runs in customer browsers.
-- Provides actual implementation via `dynatrace` global namespace.
-- Monitors page activity and sends beacons.
-- This wrapper calls into it when available.
-
-### Coordination Requirements
-
-When RUM Agent API changes:
-1. Update type definitions in this package.
-2. Update wrapper function signatures if needed.
-3. Add new wrappers for new APIs.
-4. Maintain backward compatibility.
-5. Test wrappers with both Gen2 and Gen3 agents.
-
-**Important**: This package must work with multiple agent versions deployed in customer environments.
-
-## Versioning
-
-### Compatibility Matrix
-
-Wrapper versions must be tested against:
-- Current production agent versions.
-- Previous agent versions (backward compatibility).
-
-### Deprecation Process
-
-1. Mark wrapper function as deprecated in JSDoc.
-2. Document replacement wrapper or pattern.
-3. Remove in next major version with migration guide.
-
-## Customer Usage Patterns
-
-### When to Use Sync vs Async API
-
-**Use Synchronous API When**:
-- Graceful degradation acceptable (events may be lost).
-- Agent might not be loaded (opt-in scenarios).
-- Adding instrumentation to existing code.
-
-**Use Asynchronous API When**:
-- Critical events must be sent.
-- Need explicit error handling for missing agent.
-- Consent-based agent loading.
-- Testing/debugging scenarios requiring guarantees.
-
-### Common Integration Patterns
-
-**Standard Usage**:
-```typescript
-import { sendEvent, identifyUser } from '@dynatrace/rum-javascript-api/api';
-
-// Safe - no-op if agent not loaded
-identifyUser('user@example.com');
-sendEvent({ 'event_properties.action': 'checkout' });
-```
-
-**Consent-Based Loading**:
-```typescript
-import { sendEvent } from '@dynatrace/rum-javascript-api/api/promises';
-
-async function afterConsent() {
-  try {
-    // Wait for agent, throw if not available
-    await sendEvent({ 'event_properties.consent_given': 'analytics' });
-  } catch (error) {
-    console.warn('RUM not available:', error);
-  }
-}
-```
-
-**Event Modification**:
-```typescript
-import { addEventModifier } from '@dynatrace/rum-javascript-api/api';
-
-// Add context to all events
-const unsubscribe = addEventModifier((event) => ({
-  ...event,
-  'event_properties.app_version': '2.1.0'
-}));
-```
-
-## Error Handling
-
-### DynatraceError Class
-
-Custom error thrown by asynchronous wrappers:
-- Thrown when RUM JavaScript not available within timeout.
-- Exported from both `api` and `api/promises` modules.
-- Includes descriptive error message.
-- Allows `instanceof` checking for error handling.
-
-### Error Handling Patterns
-
-```typescript
-import { sendEvent, DynatraceError } from '@dynatrace/rum-javascript-api/api/promises';
-
-try {
-  await sendEvent({ 'event_properties.test': 'value' }, undefined, 5000);
-} catch (error) {
-  if (error instanceof DynatraceError) {
-    // RUM JavaScript not available
-  }
-}
-```
-
-## Common Pitfalls
-
-### Wrapper Development
-
-- **Not handling missing `dynatrace`**: Sync wrappers must check availability.
-- **Breaking type compatibility**: Types must match RUM agent API exactly.
-- **Adding validation logic**: Wrappers are pass-through only, no validation.
-- **Incorrect timeout defaults**: Async wrappers need reasonable defaults (10s).
-- **Missing JSDoc**: Every function needs complete documentation.
-
-### Customer Usage Mistakes
-
-- **Forgetting property prefixes**: `event_properties.` required for custom events.
-- **Using async API unnecessarily**: Sync API simpler for most cases.
-- **Not handling async errors**: Async API can throw `DynatraceError`.
-- **Calling before DOM ready**: Agent might not be loaded yet.
-- **Invalid property names**: Lowercase, numbers, underscores, dots only.
-
-## Development Workflow
-
-### Adding New Wrapper Function
-
-1. **Identify new RUM API** in agent (`dynatrace` namespace).
-2. **Add types** in `source/types/` directory.
-3. **Implement synchronous wrapper** in `source/api/`:
-   - Check `dynatrace` namespace availability.
-   - Call underlying API if available.
-   - Return appropriate value or undefined.
-4. **Implement asynchronous wrapper** in `source/api/promises/`:
-   - Wait for `dynatrace` with timeout.
-   - Call underlying API if available.
-   - Throw `DynatraceError` on timeout.
-5. **Add JSDoc documentation** with examples.
-6. **Write unit tests** for both sync and async versions.
-7. **Update README.md** with usage examples.
-8. **Test with actual agent** (Gen3).
-9. **Update types.md** if new types added.
-
-### Updating Existing Wrapper
-
-1. **Check backward compatibility** implications.
-2. **Update type definitions** if signatures changed.
-3. **Modify wrapper implementations** in sync and async.
-4. **Update tests** for new behavior.
-5. **Update documentation** (README, JSDoc).
-6. **Test with existing agent versions** (compatibility).
-7. **Consider deprecation** if breaking change needed.
-
-### Testing Changes
-
-1. **Run unit tests**: `pnpm test`
-2. **Type check**: Ensure TypeScript compiles.
-3. **Test with mock agent**: Verify wrapper behavior.
-4. **Test with real agent**: Load actual RUM JavaScript.
-5. **Test edge cases**: Missing agent, timeout scenarios.
-6. **Validate examples**: Run README examples.
-7. **Test Playwright fixtures**: Verify testing framework still works.
-   - Configure test environment with access token and app ID.
-   - Run sample test using `dynatraceTesting` fixture.
-   - Verify event assertions function correctly.
-   - **Reference**: `testing.md` for testing framework validation.
-
-## Build and Distribution
-
-### Build Process
-
-- **TypeScript compilation**: Source compiled to JavaScript.
-- **Type generation**: `.d.ts` files generated for TypeScript users.
-- **Multiple exports**: Separate entry points for api, promises, types, test.
-- **Tree-shakeable**: Side-effect free, customers only bundle what they use.
-
-### Package Exports
-
-- `@dynatrace/rum-javascript-api` - Main export (types re-export).
-- `@dynatrace/rum-javascript-api/api` - Synchronous wrappers.
-- `@dynatrace/rum-javascript-api/api/promises` - Asynchronous wrappers.
-- `@dynatrace/rum-javascript-api/types` - TypeScript type definitions.
-- `@dynatrace/rum-javascript-api/test` - Playwright testing utilities.
-
-### Build Commands
-
-- `pnpm build`: Compile TypeScript to JavaScript.
-- `pnpm test`: Run Vitest unit tests with coverage.
-- `pnpm lint`: Lint TypeScript source files.
-
-## Documentation Maintenance
-
-### Keep in Sync
-
-Update documentation when:
-- **New wrapper added**: Update README API reference with function signature and examples.
-- **Type changed**: Update types.md with new type exports and usage patterns.
-- **Testing utilities updated**: Update testing.md with new fixture methods and examples.
-- **TypeScript configuration changed**: Update types.md `tsconfig.json` setup instructions.
-- **Test setup changed**: Update testing.md setup requirements (token, environment, app ID).
-- **Best practices identified**: Add to README best practices section.
-- **Common issue found**: Add to README troubleshooting or testing.md troubleshooting.
-- **New testing pattern discovered**: Add example to testing.md patterns section.
-
-### Documentation Files
-
-- **README.md**: Primary customer documentation.
-  - Installation via npm.
-  - API reference for all wrapper functions (sync and async).
-  - Error handling with `DynatraceError`.
-  - Usage examples and best practices.
-  - Event property naming conventions.
-  
-- **types.md**: TypeScript integration guide.
-  - TypeScript configuration (`typeRoots` setup).
-  - Global `window.dynatrace` type augmentation.
-  - Type import examples from package.
-  - Type inference patterns.
-  
-- **testing.md**: Playwright testing framework.
-  - Setup: access token, environment URL, app ID.
-  - `DynatraceTesting` fixture complete API reference.
-  - Test configuration with `test.use()`.
-  - Event assertion methods with timeout options.
-  - Testing patterns and troubleshooting.
-  
-- **AGENTS.md** (this file): Internal development guide for maintainers.
-
-**Note**: Any enhancement must maintain backward compatibility and not add significant overhead.