Add context field to Event interface

[nicknisi]

Summary

• Add optional context field to EventBase and EventResponseBase interfaces
• Pass through context in deserializeEvent serializer
• Add test coverage for context field deserialization

The listEvents API returns a context object containing metadata like client_id, but the deserializer was dropping it.

Test plan

• Unit tests pass with context field in test fixtures
• Manual verification against live API confirms context is now returned
• Build and lint pass

Manual verification script

Save as scripts/verify-context-field.ts and run with npx tsx scripts/verify-context-field.ts:

/**
 * Manual verification script for issue #1415
 * Tests that the context field is properly deserialized from listEvents API
 *
 * Usage: npx tsx scripts/verify-context-field.ts
 *
 * Requires WORKOS_API_KEY environment variable to be set
 */

import { WorkOS } from '../src/index';

async function main() {
  const apiKey = process.env.WORKOS_API_KEY;
  if (!apiKey) {
    console.error('Error: WORKOS_API_KEY environment variable is required');
    process.exit(1);
  }

  const workos = new WorkOS(apiKey);

  console.log('Fetching events with authentication events...\n');

  try {
    // Fetch authentication events which typically have context with client_id
    const result = await workos.events.listEvents({
      events: [
        'authentication.oauth_succeeded',
        'authentication.sso_succeeded',
        'authentication.password_succeeded',
        'authentication.magic_auth_succeeded',
      ],
      limit: 5,
    });

    console.log(`Found ${result.data.length} events\n`);

    for (const event of result.data) {
      console.log('─'.repeat(60));
      console.log(`Event ID: ${event.id}`);
      console.log(`Type: ${event.event}`);
      console.log(`Created: ${event.createdAt}`);

      if (event.context) {
        console.log('Context:', JSON.stringify(event.context, null, 2));
      } else {
        console.log('Context: (not present)');
      }
      console.log();
    }

    // Summary
    const eventsWithContext = result.data.filter((e) => e.context);
    console.log('─'.repeat(60));
    console.log(
      `\nSummary: ${eventsWithContext.length}/${result.data.length} events have context field`,
    );

    if (eventsWithContext.length > 0) {
      console.log('\n✅ Context field is being deserialized correctly!');
    } else {
      console.log(
        '\n⚠️  No events with context found. This may be expected if no recent authentication events exist.',
      );
    }
  } catch (error) {
    console.error('Error fetching events:', error);
    process.exit(1);
  }
}

main();

Fixes #1415

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds support for the context field in Event interfaces, which was previously being dropped by the deserializer despite being returned by the WorkOS API.

Changes Made

• Added optional context?: Record<string, string> field to EventBase and EventResponseBase interfaces
• Updated deserializeEvent serializer to pass through the context field from API responses
• Added test coverage with a sample context containing client_id

Implementation

The change is minimal and follows the existing pattern for optional fields on events. The context field is properly typed as an optional Record<string, string>, which matches the test fixture showing client_id as the primary use case. The deserializer correctly spreads event.context into the eventBase object, ensuring it's included in all event types that extend EventBase.

Testing

Test fixtures include context data in both the API response format (EventResponse) and the deserialized format (Event), validating that the field is properly preserved through the serialization pipeline.

Confidence Score: 5/5

• This PR is safe to merge - it adds a missing field without breaking existing functionality.
• The changes are minimal, well-tested, and follow existing patterns. The optional field addition is backward compatible, the serializer correctly passes through the data, and test coverage validates the functionality. No breaking changes or logic errors detected.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
src/common/interfaces/event.interface.ts	5/5	Added optional context field to EventBase and EventResponseBase interfaces with Record<string, string> type
src/common/serializers/event.serializer.ts	5/5	Updated deserializeEvent to pass through context field from API response to Event object
src/events/events.spec.ts	5/5	Added context test data with client_id to both Event and EventResponse fixtures

Sequence Diagram

sequenceDiagram
    participant API as WorkOS API
    participant Deserializer as deserializeEvent
    participant EventBase as EventBase Interface
    participant Client as SDK Client

    API->>Deserializer: EventResponse (with context)
    Note over Deserializer: Extract base fields
    Deserializer->>EventBase: Create EventBase object
    Note over EventBase: id, createdAt, context
    Deserializer->>Deserializer: Switch on event type
    Deserializer->>Deserializer: Deserialize event data
    Deserializer->>Client: Return Event (with context)
    Note over Client: Context now preserved

Loading