@bagelink/sdk 1.7.101 → 1.8.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bagelink/sdk",
   "type": "module",
-  "version": "1.7.101",
+  "version": "1.8.3",
   "description": "Bagel core sdk packages",
   "author": {
     "name": "Bagel Studio",

package/src/index.ts

@@ -2,6 +2,7 @@ import ax from 'axios'
 
 export * from './openAPITools'
 export { default as openAPI } from './openAPITools'
+export { createSSEStream, createSSEStreamPost, type SSEEvent, type SSEStreamOptions, StreamController, type StreamEventMap } from './openAPITools/streamClient'
 
 export type Tables = ''
 export type TableToTypeMapping = Record<Tables, any>

package/src/openAPITools/StreamController.ts

@@ -0,0 +1,372 @@
+/* eslint-disable ts/no-non-null-assertion */
+/* eslint-disable ts/no-unnecessary-condition */
+/**
+ * StreamController - Elegant event-based SSE stream management
+ * Provides a beautiful, type-safe API for consuming Server-Sent Events
+ */
+
+export interface SSEEvent<T = any> {
+	/** Event type (e.g., "token", "tool_call", "done") */
+	type: string
+	/** Event data payload */
+	data: T
+	/** Raw event string */
+	raw?: string
+}
+
+type EventHandler<T = any> = (data: T) => void
+type ErrorHandler = (error: Error) => void
+type VoidHandler = () => void
+
+/**
+ * Type-safe event map for stream events
+ * Maps event names to their data types
+ */
+export type StreamEventMap = Record<string, any>
+
+/**
+ * StreamController - Chainable event emitter for SSE streams with full type safety
+ * @template TEventMap - Map of event names to their data types
+ *
+ * @example
+ * type ChatEvents = {
+ *   token: { content: string }
+ *   tool_call: { name: string, args: any }
+ *   done: { message: string }
+ * }
+ *
+ * const stream: StreamController<ChatEvents> = ...
+ * stream.on('token', (data) => {
+ *   // `data` is typed as { content: string }
+ *   console.log(data.content)
+ * })
+ */
+export class StreamController<TEventMap extends StreamEventMap = StreamEventMap> {
+	private handlers: Map<string, Set<EventHandler>> = new Map()
+	private errorHandlers: Set<ErrorHandler> = new Set()
+	private completeHandlers: Set<VoidHandler> = new Set()
+	private abortController: AbortController
+	private _closed = false
+	private _promise: Promise<any> | null = null
+	private _resolvePromise: ((value: any) => void) | null = null
+	private _rejectPromise: ((error: Error) => void) | null = null
+
+	constructor(
+		private streamFn: (
+			onEvent: (event: SSEEvent) => void,
+			onError: (error: Error) => void,
+			onComplete: () => void
+		) => () => void
+	) {
+		this.abortController = new AbortController()
+		this.start()
+	}
+
+	private start() {
+		const cleanup = this.streamFn(
+			(event) => { this.emit(event.type, event.data) },
+			(error) => { this.emitError(error) },
+			() => { this.emitComplete() }
+		)
+
+		// Store cleanup function
+		this.abortController.signal.addEventListener('abort', () => {
+			cleanup()
+			this._closed = true
+		})
+	}
+
+	/**
+	 * Register an event handler (fully typed!)
+	 * @param event - Event type to listen for
+	 * @param handler - Handler function (data type inferred from event)
+	 * @returns this (for chaining)
+	 */
+	on<K extends keyof TEventMap | 'error' | 'complete'>(
+		event: K,
+		handler: K extends 'error'
+			? ErrorHandler
+			: K extends 'complete'
+				? VoidHandler
+				: K extends keyof TEventMap
+					? (data: TEventMap[K]) => void
+					: EventHandler
+	): this {
+		if (event === 'error') {
+			this.errorHandlers.add(handler as ErrorHandler)
+		} else if (event === 'complete') {
+			this.completeHandlers.add(handler as VoidHandler)
+		} else {
+			if (!this.handlers.has(event as string)) {
+				this.handlers.set(event as string, new Set())
+			}
+			this.handlers.get(event as string)!.add(handler as EventHandler)
+		}
+		return this
+	}
+
+	/**
+	 * Register a one-time event handler (fully typed!)
+	 * @param event - Event type to listen for
+	 * @param handler - Handler function (called once then removed, data type inferred from event)
+	 * @returns this (for chaining)
+	 */
+	once<K extends keyof TEventMap | 'error' | 'complete'>(
+		event: K,
+		handler: K extends 'error'
+			? ErrorHandler
+			: K extends 'complete'
+				? VoidHandler
+				: K extends keyof TEventMap
+					? (data: TEventMap[K]) => void
+					: EventHandler
+	): this {
+		const wrappedHandler = (data: any) => {
+			(handler as any)(data)
+			this.off(event, wrappedHandler as any)
+		}
+		return this.on(event, wrappedHandler as any)
+	}
+
+	/**
+	 * Remove an event handler (fully typed!)
+	 * @param event - Event type
+	 * @param handler - Handler to remove
+	 * @returns this (for chaining)
+	 */
+	off<K extends keyof TEventMap | 'error' | 'complete'>(
+		event: K,
+		handler: K extends 'error'
+			? ErrorHandler
+			: K extends 'complete'
+				? VoidHandler
+				: K extends keyof TEventMap
+					? (data: TEventMap[K]) => void
+					: EventHandler
+	): this {
+		if (event === 'error') {
+			this.errorHandlers.delete(handler as ErrorHandler)
+		} else if (event === 'complete') {
+			this.completeHandlers.delete(handler as VoidHandler)
+		} else {
+			this.handlers.get(event as string)?.delete(handler as EventHandler)
+		}
+		return this
+	}
+
+	/**
+	 * Remove all handlers for an event (or all events if no event specified)
+	 */
+	removeAllListeners(event?: keyof TEventMap | 'error' | 'complete'): this {
+		if (event === undefined) {
+			this.handlers.clear()
+			this.errorHandlers.clear()
+			this.completeHandlers.clear()
+		} else if (event === 'error') {
+			this.errorHandlers.clear()
+		} else if (event === 'complete') {
+			this.completeHandlers.clear()
+		} else {
+			this.handlers.delete(event as string)
+		}
+		return this
+	}
+
+	private emit(event: string, data: any) {
+		const handlers = this.handlers.get(event)
+		if (handlers) {
+			handlers.forEach((handler) => {
+				try {
+					handler(data)
+				} catch (error) {
+					console.error(`Error in handler for event "${event}":`, error)
+				}
+			})
+		}
+
+		// Resolve promise on 'done' event
+		if (event === 'done' && this._resolvePromise) {
+			this._resolvePromise(data)
+		}
+	}
+
+	private emitError(error: Error) {
+		this.errorHandlers.forEach((handler) => {
+			try {
+				handler(error)
+			} catch (err) {
+				console.error('Error in error handler:', err)
+			}
+		})
+
+		// Reject promise on error
+		if (this._rejectPromise) {
+			this._rejectPromise(error)
+		}
+	}
+
+	private emitComplete() {
+		this.completeHandlers.forEach((handler) => {
+			try {
+				handler()
+			} catch (error) {
+				console.error('Error in complete handler:', error)
+			}
+		})
+	}
+
+	/**
+	 * Close the stream
+	 */
+	close(): void {
+		if (!this._closed) {
+			this.abortController.abort()
+			this._closed = true
+		}
+	}
+
+	/**
+	 * Check if stream is closed
+	 */
+	get closed(): boolean {
+		return this._closed
+	}
+
+	/**
+	 * Convert stream to a Promise that resolves when 'done' event fires
+	 * @returns Promise that resolves with the 'done' event data
+	 */
+	toPromise<T = any>(): Promise<T> {
+		if (!this._promise) {
+			this._promise = new Promise<T>((resolve, reject) => {
+				this._resolvePromise = resolve as any
+				this._rejectPromise = reject
+			})
+		}
+		return this._promise
+	}
+
+	/**
+	 * Make the stream async iterable
+	 * Usage: for await (const event of stream) { ... }
+	 */
+	async* [Symbol.asyncIterator](): AsyncIterableIterator<SSEEvent> {
+		const events: SSEEvent[] = []
+		let resolveNext: ((event: SSEEvent | null) => void) | null = null
+		let done = false
+
+		// Capture all event types
+		const eventHandler = (type: string) => (data: any) => {
+			const event: SSEEvent = { type, data }
+			if (resolveNext) {
+				resolveNext(event)
+				resolveNext = null
+			} else {
+				events.push(event)
+			}
+		}
+
+		// Listen to all events by capturing them
+		const originalEmit = this.emit.bind(this)
+		const capturedEvents: string[] = []
+		this.emit = (event: string, data: any) => {
+			if (!capturedEvents.includes(event)) {
+				capturedEvents.push(event)
+
+				this.on(event as any, eventHandler(event))
+			}
+			originalEmit(event, data)
+		}
+
+		this.on('complete', () => {
+			done = true
+			if (resolveNext) {
+				resolveNext(null)
+				resolveNext = null
+			}
+		})
+
+		try {
+			// eslint-disable-next-line no-unmodified-loop-condition
+			while (!done) {
+				if (events.length > 0) {
+					const event = events.shift()
+					if (event) yield event
+				} else {
+					// eslint-disable-next-line no-await-in-loop
+					const event = await new Promise<SSEEvent | null>((resolve) => {
+						resolveNext = resolve
+					})
+					if (event === null) break
+					yield event
+				}
+			}
+		} finally {
+			this.close()
+		}
+	}
+
+	/**
+	 * Collect all events into an array until stream completes
+	 * @returns Promise<SSEEvent[]>
+	 */
+	async toArray(): Promise<SSEEvent[]> {
+		const events: SSEEvent[] = []
+		for await (const event of this) {
+			events.push(event)
+		}
+		return events
+	}
+
+	/**
+	 * Pipe stream events through a transform function
+	 */
+	map<R>(transform: (event: SSEEvent) => R): StreamController<TEventMap> {
+		const mappedController = new StreamController<TEventMap>(
+			(onEvent, onError, onComplete) => {
+				this.on('error' as any, onError)
+				this.on('complete' as any, onComplete)
+
+				// Forward all events through transform
+				this.handlers.forEach((_, eventType) => {
+					this.on(eventType as any, (data: any) => {
+						try {
+							const transformed = transform({ type: eventType, data })
+							onEvent({ type: eventType, data: transformed, raw: undefined })
+						} catch (error) {
+							onError(error as Error)
+						}
+					})
+				})
+
+				return () => { this.close() }
+			}
+		)
+		return mappedController
+	}
+
+	/**
+	 * Filter events based on a predicate
+	 */
+	filter(predicate: (event: SSEEvent) => boolean): StreamController<TEventMap> {
+		const filteredController = new StreamController<TEventMap>(
+			(onEvent, onError, onComplete) => {
+				this.on('error' as any, onError)
+				this.on('complete' as any, onComplete)
+
+				// Forward filtered events
+				this.handlers.forEach((_, eventType) => {
+					this.on(eventType as any, (data: any) => {
+						const event = { type: eventType, data }
+						if (predicate(event)) {
+							onEvent(event)
+						}
+					})
+				})
+
+				return () => { this.close() }
+			}
+		)
+		return filteredController
+	}
+}

package/src/openAPITools/functionGenerator.ts

@@ -1,3 +1,9 @@
+/* eslint-disable ts/strict-boolean-expressions */
+/* eslint-disable ts/no-unnecessary-condition */
+/* eslint-disable jsdoc/check-param-names */
+/* eslint-disable ts/no-non-null-assertion */
+/* eslint-disable prefer-destructuring */
+import type { SSEEventTypeInfo } from './streamDetector'
 import type {
 	OperationObject as OpenAPIOperation,
 	PathItemObject as OpenAPIPath,
@@ -8,8 +14,8 @@ import type {
 	ReferenceObject,
 	SchemaObject,
 } from './types'
+import { isSSEStream, extractSSEEventTypes, extractSSEEventInfo } from './streamDetector'
 import { dereference, isReferenceObject } from './types/utils'
-
 import {
 	cleanPath,
 	formatType,
@@ -56,6 +62,8 @@ export interface PathOperation {
 // Tracking for function generation
 const functionsInventory: Record<string, string> = {}
 const pathOperations: PathOperation[] = []
+const streamEventTypes: Record<string, string[]> = {} // Track stream endpoints and their event types
+const streamEventInfo: Record<string, SSEEventTypeInfo[]> = {} // Track detailed event info for type generation
 
 /**
  * Collects non-primitive types for import statements
@@ -339,6 +347,121 @@ function combineAllParams(
 	return `{ ${destructuredNames} }: { ${typeDefinition} } = {}`
 }
 
+/**
+ * Generates a unique type name for a stream endpoint
+ */
+function generateStreamTypeName(path: string): string {
+	return `${toPascalCase(
+		path
+			.split('/')
+			.filter(p => p && !/\{|\}/.test(p))
+			.join('_')
+	)}StreamEvents`
+}
+
+/**
+ * Generates a Stream function for SSE endpoints with full type safety
+ * @param method - The HTTP method
+ * @param path - The original API path
+ * @param formattedPath - The formatted API path
+ * @param allParams - The combined parameter string
+ * @param requestBodyPayload - The request body payload
+ * @param eventTypes - Array of SSE event types
+ * @returns A string with the SSE stream function
+ */
+function generateStreamFunction(
+	method: string,
+	path: string,
+	formattedPath: string,
+	allParams: string,
+	requestBodyPayload: string,
+	eventTypes?: string[]
+): string {
+	if (allParams === 'undefined') { allParams = '' }
+
+	// Extract parameter names for the stream call (unused but kept for future use)
+	// const paramNames = allParams ? allParams.match(/\w+(?=\s*[?:])/g) || [] : []
+
+	const bodyVar = requestBodyPayload || '{}'
+	const baseUrlRef = 'axios.defaults.baseURL || ""'
+
+	// Generate type name for this stream
+	const streamTypeName = generateStreamTypeName(path)
+
+	// Store event types for later type generation
+	if (eventTypes?.length) {
+		streamEventTypes[streamTypeName] = eventTypes
+	}
+
+	const eventTypesComment = eventTypes?.length
+		? `\n   * Event types: ${eventTypes.map(t => `"${t}"`).join(', ')}`
+		: ''
+
+	const eventTypesExample = eventTypes?.length
+		? eventTypes.map(t => `\n   *   .on('${t}', (data) => console.log(data))`).join('')
+		: '\n   *   .on(\'message\', (data) => console.log(data))'
+
+	const typeAnnotation = eventTypes?.length
+		? `StreamController<${streamTypeName}>`
+		: 'StreamController'
+
+	// Convert formattedPath from string representation to actual path for URL construction
+	// formattedPath can be either 'path' or `path/${param}` (as strings)
+	const pathForUrl = formattedPath.startsWith('`')
+		? formattedPath.slice(1, -1) // Remove backticks to get the content
+		: formattedPath.slice(1, -1) // Remove quotes to get the content
+
+	if (method === 'post') {
+		return `{
+  /**
+   * Stream SSE events from this endpoint (returns StreamController)${eventTypesComment}
+   * 
+   * @example
+   * const stream = api.endpoint.stream(params)${eventTypesExample}
+   *   .on('error', (err) => console.error(err))
+   *   .on('complete', () => console.log('Done!'))
+   * 
+   * // Close stream when needed
+   * stream.close()
+   */
+  stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
+    return createSSEStreamPost<${streamTypeName}>(url, ${bodyVar}, options)
+  },
+  /**
+   * Regular POST request (non-streaming)
+   */
+  post: async (${allParams}): Promise<AxiosResponse<any>> => {
+    return axios.post(${formattedPath}, ${bodyVar})
+  }
+}`
+	} else {
+		return `{
+  /**
+   * Stream SSE events from this endpoint (returns StreamController)${eventTypesComment}
+   * 
+   * @example
+   * const stream = api.endpoint.stream(params)${eventTypesExample}
+   *   .on('error', (err) => console.error(err))
+   *   .on('complete', () => console.log('Done!'))
+   * 
+   * // Close stream when needed
+   * stream.close()
+   */
+  stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
+    return createSSEStream<${streamTypeName}>(url, options)
+  },
+  /**
+   * Regular GET request (non-streaming)
+   */
+  get: async (${allParams}): Promise<AxiosResponse<any>> => {
+    return axios.get(${formattedPath})
+  }
+}`
+	}
+}
+
 /**
  * Generates an Axios function call as a string
  * @param method - The HTTP method
@@ -444,6 +567,9 @@ function generateFunctionForOperation(
 ): string {
 	if (!operation) { return '' }
 
+	// Check if this is an SSE stream endpoint
+	const isStream = isSSEStream(operation)
+
 	// Validate: GET and DELETE requests should not have request bodies
 	const methodLower = method.toLowerCase()
 	if (['get', 'delete'].includes(methodLower) && operation.requestBody) {
@@ -493,6 +619,27 @@ function generateFunctionForOperation(
 	// Create JSDoc comment with OpenAPI documentation
 	const functionComment = buildJSDocComment(operation, method, path)
 
+	// Generate stream function for SSE endpoints
+	if (isStream) {
+		const eventTypes = extractSSEEventTypes(operation)
+		const eventInfo = extractSSEEventInfo(operation)
+
+		// Store detailed event info for type generation
+		const streamTypeName = generateStreamTypeName(path)
+		if (eventInfo?.length) {
+			streamEventInfo[streamTypeName] = eventInfo
+		}
+
+		return functionComment + generateStreamFunction(
+			method,
+			path,
+			formatPathWithParams(path),
+			allParams,
+			requestBodyPayload,
+			eventTypes
+		)
+	}
+
 	return functionComment + generateAxiosFunction(
 		method,
 		formatPathWithParams(path),
@@ -667,6 +814,76 @@ export const ${parent} = ${JSON.stringify(object, undefined, 2)};\n`
 	return fileTemplate(tsString, allTypes, baseUrl)
 }
 
+/**
+ * Generates TypeScript type definitions for stream events
+ * Uses detailed event info if available, falls back to simple event list
+ * @returns TypeScript type definitions string
+ */
+function generateStreamEventTypeDefinitions(): string {
+	if (Object.keys(streamEventTypes).length === 0) {
+		return ''
+	}
+
+	let typeDefs = '\n// ============================================================================\n'
+	typeDefs += '// Stream Event Type Definitions (Fully Typed!)\n'
+	typeDefs += '// ============================================================================\n\n'
+
+	for (const [typeName, events] of Object.entries(streamEventTypes)) {
+		const eventInfo = streamEventInfo[typeName]
+
+		typeDefs += `/**\n * Event types for ${typeName.replace('StreamEvents', '')} stream\n`
+		typeDefs += ` * Events: ${events.map(e => `"${e}"`).join(', ')}\n`
+
+		// Add event descriptions if available
+		if (eventInfo?.length) {
+			typeDefs += ` *\n`
+			for (const info of eventInfo) {
+				typeDefs += ` * - **${info.name}**: ${info.description || 'Event data'}\n`
+			}
+		}
+
+		typeDefs += ` */\n`
+		typeDefs += `export interface ${typeName} {\n`
+
+		// Generate event type definitions with field information if available
+		if (eventInfo?.length) {
+			for (const info of eventInfo) {
+				typeDefs += `  /**\n   * ${info.description || info.name}\n`
+
+				if (info.fields?.length) {
+					info.fields.forEach((field) => {
+						typeDefs += `   * - \`${field.name}\`: ${field.description || 'Field data'}\n`
+					})
+				}
+
+				typeDefs += `   */\n`
+
+				// Generate interface for this event
+				if (info.fields?.length) {
+					typeDefs += `  ${info.name}: {\n`
+					for (const field of info.fields) {
+						typeDefs += `    /** ${field.description || field.name} */\n`
+						typeDefs += `    ${field.name}: any\n`
+					}
+					typeDefs += `  }\n`
+				} else {
+					typeDefs += `  ${info.name}: any\n`
+				}
+			}
+		} else {
+			// Fallback: simple event list without field info
+			for (const event of events) {
+				typeDefs += `  /** ${event} event data */\n`
+				typeDefs += `  ${event}: any\n`
+			}
+		}
+
+		typeDefs += '}\n\n'
+	}
+
+	return typeDefs
+}
+
 /**
  * Generates the TypeScript file template
  * @param tsString - The generated TypeScript code
@@ -679,9 +896,12 @@ function fileTemplate(
 	typeForImport: string[],
 	baseURL: string
 ): string {
+	const streamTypeDefs = generateStreamEventTypeDefinitions()
+
 	const templateCode = `import ax from 'axios';
 import type { AxiosResponse } from 'axios';
 import type { ${typeForImport.join(', ')} } from './types.d';
+import { createSSEStream, createSSEStreamPost, StreamController, type SSEStreamOptions, type SSEEvent } from './streamClient';
 
 /**
  * Options for file upload operations
@@ -695,6 +915,24 @@ export interface UploadOptions {
 	tags?: string[]
 }
 
+/**
+ * Export SSE stream utilities for direct use
+ * 
+ * @example Chainable event handlers
+ * const stream = createSSEStream(url)
+ *   .on('token', (data) => console.log(data))
+ *   .on('done', () => console.log('Complete!'))
+ * 
+ * @example Async iteration
+ * for await (const event of createSSEStream(url)) {
+ *   console.log(event.type, event.data)
+ * }
+ * 
+ * @example Promise-based
+ * const result = await createSSEStream(url).toPromise()
+ */
+export { createSSEStream, createSSEStreamPost, StreamController, type SSEStreamOptions, type SSEEvent } from './streamClient';
+${streamTypeDefs}
 /**
  * Configured axios instance for API requests
  * @example

package/src/openAPITools/index.ts

@@ -35,4 +35,6 @@ export default async (openApiUrl: string, baseUrl: string): Promise<OpenAPIRespo
 	}
 }
 
+export * from './streamClient'
+export * from './streamDetector'
 export * from './types'