feat: add SSE (Server-Sent Events) support

[cc-hearts]

PR: feat: add SSE (Server-Sent Events) support

Summary

Added SSE (Server-Sent Events) support to the Request class, enabling streaming HTTP connections with a clean, composable API.

Motivation

Previously, the Request class only supported standard HTTP requests without streaming capabilities. This PR adds SSE support, which is essential for:

• Real-time data streaming (e.g., live feeds, notifications)
• AI chat completions (e.g., GPT streaming responses)
• Server-sent updates without polling

Key Features

1. Based on Fetch API (not native EventSource)

Unlike the browser's native EventSource, this implementation:

• ✅ Supports custom Headers (e.g., Authorization)
• ✅ Supports POST requests
• ✅ Supports all HTTP methods
• ✅ Works in Node.js environments

2. New Types Added

// SSE message event
interface SSEMessageEvent {
  event?: string    // Event type (from `event:` field)
  data: string      // Message data
  id?: string       // Last event ID (from `id:` field)
  retry?: number    // Retry interval in milliseconds
}

// SSE callback handlers
interface SSECallbacks {
  onMessage?: (event: SSEMessageEvent) => void
  onOpen?: () => void
  onError?: (error: unknown) => void
  onClose?: () => void
}

// SSE configuration
interface SSEConfig extends SSECallbacks {
  sse: true
  headers?: Record<string, string>
  data?: unknown
}

3. New Method: sse()

const api = new Request('https://api.example.com')

// GET SSE
const handle = api.sse('/events', {
  onMessage(event) {
    console.log('Received:', event.data)
  },
  onOpen() {
    console.log('Connection opened')
  },
  onError(error) {
    console.error('Error:', error)
  },
  onClose() {
    console.log('Connection closed')
  }
})

// Cancel connection
handle.abort()

4. POST SSE Example (AI Streaming)

const handle = api.sse('/chat/completions', {
  method: 'POST',
  data: {
    prompt: 'Hello',
    model: 'gpt-4'
  },
  onMessage(event) {
    const data = JSON.parse(event.data)
    console.log('AI reply:', data.content)
  }
})

5. Interceptor Support

SSE requests automatically include headers added by request interceptors:

const addAuth: RequestInterceptor = (config) => ({
  ...config,
  headers: {
    ...config.headers,
    Authorization: `Bearer ${getToken()}`
  }
})

api.useRequestInterceptor(addAuth)

// This SSE request will include the Authorization header
api.sse('/protected/events', { ... })

Implementation Details

SSE Parser

• Properly handles the SSE protocol specification
• Supports multi-line data fields
• Handles comments (lines starting with :)
• Properly parses event:, data:, id:, and retry: fields

Memory Management

• Uses AbortController for clean cancellation
• Properly cleans up resources on connection close
• Handles errors without memory leaks

Testing

The implementation has been tested with:

• ✅ TypeScript compilation (no type errors)
• ✅ Build process completes successfully
• ✅ Documentation generation works

Breaking Changes

None. This is a purely additive feature.

Documentation

Updated both English and Chinese README files with:

• Basic usage examples
• POST SSE examples
• Interceptor integration examples
• Type definitions reference

Checklist

• Code follows the existing code style
• TypeScript types are properly defined
• Documentation is updated
• Build passes successfully
• No breaking changes
• Commit message follows conventional commits format

PR Link

Create PR: https://github.com/cenova-labs/utils/pull/new/feature/sse-support