@bagelink/sdk 1.7.101 → 1.8.3

package/src/openAPITools/streamClient.ts

@@ -0,0 +1,247 @@
+/* eslint-disable ts/no-unnecessary-condition */
+/* eslint-disable no-await-in-loop */
+/* eslint-disable ts/strict-boolean-expressions */
+/* eslint-disable ts/use-unknown-in-catch-callback-variable */
+/**
+ * SSE (Server-Sent Events) Client Utilities
+ * Provides utilities for consuming Server-Sent Events streams
+ */
+
+import type { StreamEventMap } from './StreamController'
+import { StreamController } from './StreamController'
+
+export { type SSEEvent, StreamController, type StreamEventMap } from './StreamController'
+
+export interface SSEStreamOptions {
+	/** Additional headers to send with the request */
+	headers?: Record<string, string>
+	/** Whether to include credentials (cookies) with the request */
+	withCredentials?: boolean
+}
+
+/**
+ * Creates an SSE stream consumer with elegant event-based API
+ * @param url - The SSE endpoint URL
+ * @param options - Stream options
+ * @returns StreamController for chainable event handling
+ *
+ * @example
+ * ```typescript
+ * const stream = createSSEStream(url)
+ *   .on('token', data => console.log(data))
+ *   .on('done', () => console.log('Complete!'))
+ *   .on('error', err => console.error(err))
+ *
+ * // Close when needed
+ * stream.close()
+ * ```
+ */
+export function createSSEStream<TEventMap extends StreamEventMap = StreamEventMap>(
+	url: string,
+	options: SSEStreamOptions = {}
+): StreamController<TEventMap> {
+	const { headers = {}, withCredentials = true } = options
+
+	return new StreamController((onEvent, onError, onComplete) => {
+		const controller = new AbortController()
+		const { signal } = controller
+
+		// Start the fetch request
+		fetch(url, {
+			method: 'GET',
+			headers: {
+				Accept: 'text/event-stream',
+				...headers,
+			},
+			credentials: withCredentials ? 'include' : 'same-origin',
+			signal,
+		})
+			.then(async (response) => {
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+				}
+
+				if (!response.body) {
+					throw new Error('Response body is null')
+				}
+
+				const reader = response.body.getReader()
+				const decoder = new TextDecoder()
+				let buffer = ''
+
+				try {
+					while (true) {
+						const { done, value } = await reader.read()
+
+						if (done) {
+							onComplete()
+							break
+						}
+
+						// Decode the chunk and add to buffer
+						buffer += decoder.decode(value, { stream: true })
+
+						// Process complete events in the buffer
+						const lines = buffer.split('\n')
+						buffer = lines.pop() || '' // Keep incomplete line in buffer
+
+						let eventType = ''
+						let eventData = ''
+
+						for (const line of lines) {
+							if (line.startsWith('event:')) {
+								eventType = line.slice(6).trim()
+							} else if (line.startsWith('data:')) {
+								eventData = line.slice(5).trim()
+							} else if (line === '' && eventData) {
+								// Empty line indicates end of event
+								try {
+									const parsedData = JSON.parse(eventData)
+									onEvent({
+										type: eventType || 'message',
+										data: parsedData,
+										raw: eventData,
+									})
+								} catch {
+									// If not JSON, pass as string
+									onEvent({
+										type: eventType || 'message',
+										data: eventData,
+										raw: eventData,
+									})
+								}
+								eventType = ''
+								eventData = ''
+							}
+						}
+					}
+				} catch (error) {
+					if (error instanceof Error && error.name !== 'AbortError') {
+						onError(error)
+					}
+				}
+			})
+			.catch((error) => {
+				if (error.name !== 'AbortError') {
+					onError(error)
+				}
+			})
+
+		// Return cleanup function
+		return () => { controller.abort() }
+	})
+}
+
+/**
+ * Creates an SSE stream consumer for POST requests with elegant event-based API
+ * @param url - The SSE endpoint URL
+ * @param body - Request body
+ * @param options - Stream options
+ * @returns StreamController for chainable event handling
+ *
+ * @example
+ * ```typescript
+ * const stream = createSSEStreamPost(url, { message: 'Hello' })
+ *   .on('token', data => console.log(data))
+ *   .on('done', () => console.log('Complete!'))
+ *   .on('error', err => console.error(err))
+ * ```
+ */
+export function createSSEStreamPost<TEventMap extends StreamEventMap = StreamEventMap, TBody = any>(
+	url: string,
+	body: TBody,
+	options: SSEStreamOptions = {}
+): StreamController<TEventMap> {
+	const { headers = {}, withCredentials = true } = options
+
+	return new StreamController((onEvent, onError, onComplete) => {
+		const controller = new AbortController()
+		const { signal } = controller
+
+		// Start the fetch request
+		fetch(url, {
+			method: 'POST',
+			headers: {
+				'Accept': 'text/event-stream',
+				'Content-Type': 'application/json',
+				...headers,
+			},
+			credentials: withCredentials ? 'include' : 'same-origin',
+			body: JSON.stringify(body),
+			signal,
+		})
+			.then(async (response) => {
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+				}
+
+				if (!response.body) {
+					throw new Error('Response body is null')
+				}
+
+				const reader = response.body.getReader()
+				const decoder = new TextDecoder()
+				let buffer = ''
+
+				try {
+					while (true) {
+						const { done, value } = await reader.read()
+
+						if (done) {
+							onComplete()
+							break
+						}
+
+						// Decode the chunk and add to buffer
+						buffer += decoder.decode(value, { stream: true })
+
+						// Process complete events in the buffer
+						const lines = buffer.split('\n')
+						buffer = lines.pop() || '' // Keep incomplete line in buffer
+
+						let eventType = ''
+						let eventData = ''
+
+						for (const line of lines) {
+							if (line.startsWith('event:')) {
+								eventType = line.slice(6).trim()
+							} else if (line.startsWith('data:')) {
+								eventData = line.slice(5).trim()
+							} else if (line === '' && eventData) {
+								// Empty line indicates end of event
+								try {
+									const parsedData = JSON.parse(eventData)
+									onEvent({
+										type: eventType || 'message',
+										data: parsedData,
+										raw: eventData,
+									})
+								} catch {
+									// If not JSON, pass as string
+									onEvent({
+										type: eventType || 'message',
+										data: eventData,
+										raw: eventData,
+									})
+								}
+								eventType = ''
+								eventData = ''
+							}
+						}
+					}
+				} catch (error) {
+					if (error instanceof Error && error.name !== 'AbortError') {
+						onError(error)
+					}
+				}
+			})
+			.catch((error) => {
+				if (error.name !== 'AbortError') {
+					onError(error)
+				}
+			})
+
+		// Return cleanup function
+		return () => { controller.abort() }
+	})
+}

package/src/openAPITools/streamDetector.ts

@@ -0,0 +1,207 @@
+import type { OperationObject as OpenAPIOperation } from './types'
+
+/**
+ * Detects if an operation is an SSE (Server-Sent Events) stream endpoint
+ *
+ * Primary detection: Checks for text/event-stream content type in responses
+ * Fallback: Only if no content type is specified, check for explicit SSE keywords
+ *
+ * @param operation - The OpenAPI operation object
+ * @returns Whether the operation is an SSE stream
+ */
+export function isSSEStream(operation: OpenAPIOperation): boolean {
+	const responses = operation.responses || {}
+
+	// Check all response codes (200, 201, etc.)
+	for (const [statusCode, response] of Object.entries(responses)) {
+		// Only check successful responses (2xx)
+		if (!statusCode.startsWith('2')) continue
+
+		// Skip reference objects for now
+		if ('$ref' in response) continue
+
+		const content = (response as any).content || {}
+		const contentTypes = Object.keys(content)
+
+		// If response has content types defined
+		if (contentTypes.length > 0) {
+			// It's a stream if text/event-stream is present
+			// (even if application/json is also present as a fallback)
+			if ('text/event-stream' in content) {
+				return true
+			}
+		}
+	}
+
+	// If we checked responses and found only application/json (no text/event-stream), it's not a stream
+	const hasDefinedContentTypes = Object.entries(responses).some(([statusCode, response]) => {
+		if (!statusCode.startsWith('2')) return false
+		if ('$ref' in response) return false
+		const content = (response as any).content || {}
+		return Object.keys(content).length > 0
+	})
+
+	if (hasDefinedContentTypes) {
+		return false
+	}
+
+	// Fallback: If no content types are defined at all, check description
+	// (Some OpenAPI specs might not properly define response content types)
+	const description = operation.description?.toLowerCase() || ''
+	const summary = operation.summary?.toLowerCase() || ''
+
+	const hasExplicitSSEMention
+		= /\bsse\b/.test(description)
+			|| /server-sent events/i.test(description)
+			|| /text\/event-stream/i.test(description)
+			|| /\bsse\b/.test(summary)
+
+	return hasExplicitSSEMention
+}
+
+/**
+ * Information about an SSE event type including its fields
+ */
+export interface SSEEventTypeInfo {
+	/** Event type name */
+	name: string
+	/** Event description */
+	description?: string
+	/** Fields in the event data */
+	fields?: Array<{
+		name: string
+		description?: string
+		type?: string
+	}>
+}
+
+/**
+ * Extracts SSE event types from operation description and examples
+ *
+ * Supports multiple documentation formats:
+ * 1. Markdown format: "1. **event_name**: Description"
+ * 2. Legacy format: type: "event_name"
+ * 3. SSE examples: event: event_name
+ *
+ * @param operation - The OpenAPI operation object
+ * @returns Array of event types or undefined
+ */
+export function extractSSEEventTypes(operation: OpenAPIOperation): string[] | undefined {
+	const description = operation.description || ''
+	const types = new Set<string>()
+
+	// Method 1: Extract from markdown numbered lists with bold event names
+	// Pattern: "1. **event_name**: Description"
+	const markdownMatches = description.matchAll(/^\d+\.\s+\*\*([a-z_]+)\*\*/gm)
+	for (const match of markdownMatches) {
+		types.add(match[1])
+	}
+
+	// Method 2: Legacy format - type: "event_name"
+	const typeMatches = description.matchAll(/type:\s*"([^"]+)"/g)
+	for (const match of typeMatches) {
+		types.add(match[1])
+	}
+
+	// Method 3: Extract from SSE examples in response content
+	const responses = operation.responses || {}
+	for (const response of Object.values(responses)) {
+		if ('content' in response) {
+			const content = (response as any).content || {}
+			const eventStream = content['text/event-stream']
+			if (eventStream?.example) {
+				// Parse SSE format: event: event_name
+				const exampleMatches = eventStream.example.matchAll(/^event:\s*([a-z_]+)/gm)
+				for (const match of exampleMatches) {
+					types.add(match[1])
+				}
+			}
+		}
+	}
+
+	return types.size > 0 ? Array.from(types).sort() : undefined
+}
+
+/**
+ * Extracts detailed SSE event information including field definitions
+ *
+ * Parses markdown documentation format:
+ * ```
+ * 1. **event_name**: Event description
+ *    - `field_name`: Field description
+ *    - `another_field`: Another description
+ * ```
+ *
+ * @param operation - The OpenAPI operation object
+ * @returns Array of event type information with fields
+ */
+export function extractSSEEventInfo(operation: OpenAPIOperation): SSEEventTypeInfo[] | undefined {
+	const description = operation.description || ''
+	const eventInfos: SSEEventTypeInfo[] = []
+
+	// Split description into sections by numbered events
+	const eventSections = description.split(/(?=^\d+\.\s+\*\*)/m)
+
+	for (const section of eventSections) {
+		// Extract event name and description
+		const eventMatch = section.match(/^\d+\.\s+\*\*([a-z_]+)\*\*:\s*([^\n]+)/m)
+		if (!eventMatch) continue
+
+		const [, eventName, eventDescription] = eventMatch
+
+		// Extract fields from the section
+		const fields: Array<{ name: string, description?: string, type?: string }> = []
+		const fieldMatches = section.matchAll(/^\s+[-*]\s+`([^`]+)`:\s*([^\n]+)/gm)
+
+		for (const fieldMatch of fieldMatches) {
+			const [, fieldName, fieldDescription] = fieldMatch
+			fields.push({
+				name: fieldName,
+				description: fieldDescription.trim(),
+			})
+		}
+
+		eventInfos.push({
+			name: eventName,
+			description: eventDescription,
+			fields: fields.length > 0 ? fields : undefined,
+		})
+	}
+
+	// If no markdown events found, try to extract from examples
+	if (eventInfos.length === 0) {
+		const responses = operation.responses || {}
+		for (const response of Object.values(responses)) {
+			if ('content' in response) {
+				const content = (response as any).content || {}
+				const eventStream = content['text/event-stream']
+				if (eventStream?.example) {
+					// Parse example JSON to extract field names
+					const exampleMatches = eventStream.example.matchAll(/data:\s*(\{[^}]+\})/g)
+					const seenEvents = new Set<string>()
+
+					for (const match of exampleMatches) {
+						try {
+							const data = JSON.parse(match[1])
+							if (data.type && !seenEvents.has(data.type)) {
+								seenEvents.add(data.type)
+								const fields = Object.keys(data)
+									.filter(key => key !== 'type' && key !== 'sequence')
+									.map(key => ({ name: key }))
+
+								eventInfos.push({
+									name: data.type,
+									fields: fields.length > 0 ? fields : undefined,
+								})
+							}
+						} catch {
+							// Skip invalid JSON
+						}
+					}
+				}
+			}
+		}
+	}
+
+	return eventInfos.length > 0 ? eventInfos : undefined
+}