@bagelink/sdk 1.7.104 → 1.8.3

package/dist/index.cjs

@@ -7,23 +7,109 @@ function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'defau
 const axios__default = /*#__PURE__*/_interopDefaultCompat(axios$1);
 
 function isSSEStream(operation) {
-  const description = operation.description?.toLowerCase() || "";
-  const summary = operation.summary?.toLowerCase() || "";
-  const hasSSEKeywords = description.includes("sse") || description.includes("server-sent events") || description.includes("event stream") || summary.includes("stream");
   const responses = operation.responses || {};
-  const hasEventStreamContentType = Object.values(responses).some((response) => {
-    if ("content" in response) {
-      return "text/event-stream" in (response.content || {});
+  for (const [statusCode, response] of Object.entries(responses)) {
+    if (!statusCode.startsWith("2")) continue;
+    if ("$ref" in response) continue;
+    const content = response.content || {};
+    const contentTypes = Object.keys(content);
+    if (contentTypes.length > 0) {
+      if ("text/event-stream" in content) {
+        return true;
+      }
     }
-    return false;
+  }
+  const hasDefinedContentTypes = Object.entries(responses).some(([statusCode, response]) => {
+    if (!statusCode.startsWith("2")) return false;
+    if ("$ref" in response) return false;
+    const content = response.content || {};
+    return Object.keys(content).length > 0;
   });
-  return hasSSEKeywords || hasEventStreamContentType;
+  if (hasDefinedContentTypes) {
+    return false;
+  }
+  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;
 }
 function extractSSEEventTypes(operation) {
   const description = operation.description || "";
+  const types = /* @__PURE__ */ new Set();
+  const markdownMatches = description.matchAll(/^\d+\.\s+\*\*([a-z_]+)\*\*/gm);
+  for (const match of markdownMatches) {
+    types.add(match[1]);
+  }
   const typeMatches = description.matchAll(/type:\s*"([^"]+)"/g);
-  const types = Array.from(typeMatches).map((match) => match[1]);
-  return types.length > 0 ? types : void 0;
+  for (const match of typeMatches) {
+    types.add(match[1]);
+  }
+  const responses = operation.responses || {};
+  for (const response of Object.values(responses)) {
+    if ("content" in response) {
+      const content = response.content || {};
+      const eventStream = content["text/event-stream"];
+      if (eventStream?.example) {
+        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() : void 0;
+}
+function extractSSEEventInfo(operation) {
+  const description = operation.description || "";
+  const eventInfos = [];
+  const eventSections = description.split(/(?=^\d+\.\s+\*\*)/m);
+  for (const section of eventSections) {
+    const eventMatch = section.match(/^\d+\.\s+\*\*([a-z_]+)\*\*:\s*([^\n]+)/m);
+    if (!eventMatch) continue;
+    const [, eventName, eventDescription] = eventMatch;
+    const fields = [];
+    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 : void 0
+    });
+  }
+  if (eventInfos.length === 0) {
+    const responses = operation.responses || {};
+    for (const response of Object.values(responses)) {
+      if ("content" in response) {
+        const content = response.content || {};
+        const eventStream = content["text/event-stream"];
+        if (eventStream?.example) {
+          const exampleMatches = eventStream.example.matchAll(/data:\s*(\{[^}]+\})/g);
+          const seenEvents = /* @__PURE__ */ new Set();
+          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 : void 0
+                });
+              }
+            } catch {
+            }
+          }
+        }
+      }
+    }
+  }
+  return eventInfos.length > 0 ? eventInfos : void 0;
 }
 
 function getPath(pathsObject, path) {
@@ -305,6 +391,7 @@ const primitiveTypes = [
 const functionsInventory = {};
 const pathOperations = [];
 const streamEventTypes = {};
+const streamEventInfo = {};
 function collectTypeForImportStatement(typeName) {
   typeName = typeName.trim().replace("[]", "");
   if (typeName.includes("|")) {
@@ -488,6 +575,7 @@ function generateStreamFunction(method, path, formattedPath, allParams, requestB
   const eventTypesExample = eventTypes?.length ? eventTypes.map((t) => `
    *   .on('${t}', (data) => console.log(data))`).join("") : "\n   *   .on('message', (data) => console.log(data))";
   const typeAnnotation = eventTypes?.length ? `StreamController<${streamTypeName}>` : "StreamController";
+  const pathForUrl = formattedPath.startsWith("`") ? formattedPath.slice(1, -1) : formattedPath.slice(1, -1);
   if (method === "post") {
     return `{
   /**
@@ -502,7 +590,7 @@ function generateStreamFunction(method, path, formattedPath, allParams, requestB
    * stream.close()
    */
   stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
-    const url = \`\${${baseUrlRef}}${formattedPath}\`
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
     return createSSEStreamPost<${streamTypeName}>(url, ${bodyVar}, options)
   },
   /**
@@ -526,7 +614,7 @@ function generateStreamFunction(method, path, formattedPath, allParams, requestB
    * stream.close()
    */
   stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
-    const url = \`\${${baseUrlRef}}${formattedPath}\`
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
     return createSSEStream<${streamTypeName}>(url, options)
   },
   /**
@@ -626,6 +714,11 @@ function generateFunctionForOperation(method, path, operation) {
   const functionComment = buildJSDocComment(operation, method, path);
   if (isStream) {
     const eventTypes = extractSSEEventTypes(operation);
+    const eventInfo = extractSSEEventInfo(operation);
+    const streamTypeName = generateStreamTypeName(path);
+    if (eventInfo?.length) {
+      streamEventInfo[streamTypeName] = eventInfo;
+    }
     return functionComment + generateStreamFunction(
       method,
       path,
@@ -738,19 +831,60 @@ function generateStreamEventTypeDefinitions() {
   typeDefs += "// Stream Event Type Definitions (Fully Typed!)\n";
   typeDefs += "// ============================================================================\n\n";
   for (const [typeName, events] of Object.entries(streamEventTypes)) {
+    const eventInfo = streamEventInfo[typeName];
     typeDefs += `/**
  * Event types for ${typeName.replace("StreamEvents", "")} stream
 `;
     typeDefs += ` * Events: ${events.map((e) => `"${e}"`).join(", ")}
- */
+`;
+    if (eventInfo?.length) {
+      typeDefs += ` *
+`;
+      for (const info of eventInfo) {
+        typeDefs += ` * - **${info.name}**: ${info.description || "Event data"}
+`;
+      }
+    }
+    typeDefs += ` */
 `;
     typeDefs += `export interface ${typeName} {
 `;
-    for (const event of events) {
-      typeDefs += `  /** ${event} event data */
+    if (eventInfo?.length) {
+      for (const info of eventInfo) {
+        typeDefs += `  /**
+   * ${info.description || info.name}
+`;
+        if (info.fields?.length) {
+          info.fields.forEach((field) => {
+            typeDefs += `   * - \`${field.name}\`: ${field.description || "Field data"}
+`;
+          });
+        }
+        typeDefs += `   */
+`;
+        if (info.fields?.length) {
+          typeDefs += `  ${info.name}: {
+`;
+          for (const field of info.fields) {
+            typeDefs += `    /** ${field.description || field.name} */
+`;
+            typeDefs += `    ${field.name}: any
+`;
+          }
+          typeDefs += `  }
 `;
-      typeDefs += `  ${event}: any // TODO: Define specific type from OpenAPI schema
+        } else {
+          typeDefs += `  ${info.name}: any
 `;
+        }
+      }
+    } else {
+      for (const event of events) {
+        typeDefs += `  /** ${event} event data */
+`;
+        typeDefs += `  ${event}: any
+`;
+      }
     }
     typeDefs += "}\n\n";
   }
@@ -1584,6 +1718,7 @@ exports.StreamController = StreamController;
 exports.createSSEStream = createSSEStream;
 exports.createSSEStreamPost = createSSEStreamPost;
 exports.dereference = dereference;
+exports.extractSSEEventInfo = extractSSEEventInfo;
 exports.extractSSEEventTypes = extractSSEEventTypes;
 exports.formatAPIErrorMessage = formatAPIErrorMessage;
 exports.getPath = getPath;

package/dist/index.d.cts

@@ -508,16 +508,55 @@ interface SecurityRequirementObject {
 
 /**
  * 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
  */
 declare function isSSEStream(operation: OperationObject): boolean;
 /**
- * Extracts SSE event types from operation description
+ * Information about an SSE event type including its fields
+ */
+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
  */
 declare function extractSSEEventTypes(operation: OperationObject): string[] | 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
+ */
+declare function extractSSEEventInfo(operation: OperationObject): SSEEventTypeInfo[] | undefined;
 
 interface OpenAPIResponse {
     types: string;
@@ -629,5 +668,5 @@ declare class Bagel {
     uploadFile<T>(file: File, options?: UploadOptions): Promise<T>;
 }
 
-export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, _default as openAPI };
-export type { BaseParameterObject, CallbackObject, CallbacksObject, ComponentsObject, ContactObject, ContentObject, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SSEEvent, SSEStreamOptions, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, StreamEventMap, TableToTypeMapping, Tables, TagObject, TypeFormatT, UploadOptions, User, XmlObject };
+export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventInfo, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, _default as openAPI };
+export type { BaseParameterObject, CallbackObject, CallbacksObject, ComponentsObject, ContactObject, ContentObject, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SSEEvent, SSEEventTypeInfo, SSEStreamOptions, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, StreamEventMap, TableToTypeMapping, Tables, TagObject, TypeFormatT, UploadOptions, User, XmlObject };

package/dist/index.d.mts

@@ -508,16 +508,55 @@ interface SecurityRequirementObject {
 
 /**
  * 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
  */
 declare function isSSEStream(operation: OperationObject): boolean;
 /**
- * Extracts SSE event types from operation description
+ * Information about an SSE event type including its fields
+ */
+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
  */
 declare function extractSSEEventTypes(operation: OperationObject): string[] | 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
+ */
+declare function extractSSEEventInfo(operation: OperationObject): SSEEventTypeInfo[] | undefined;
 
 interface OpenAPIResponse {
     types: string;
@@ -629,5 +668,5 @@ declare class Bagel {
     uploadFile<T>(file: File, options?: UploadOptions): Promise<T>;
 }
 
-export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, _default as openAPI };
-export type { BaseParameterObject, CallbackObject, CallbacksObject, ComponentsObject, ContactObject, ContentObject, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SSEEvent, SSEStreamOptions, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, StreamEventMap, TableToTypeMapping, Tables, TagObject, TypeFormatT, UploadOptions, User, XmlObject };
+export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventInfo, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, _default as openAPI };
+export type { BaseParameterObject, CallbackObject, CallbacksObject, ComponentsObject, ContactObject, ContentObject, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SSEEvent, SSEEventTypeInfo, SSEStreamOptions, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, StreamEventMap, TableToTypeMapping, Tables, TagObject, TypeFormatT, UploadOptions, User, XmlObject };

package/dist/index.d.ts

@@ -508,16 +508,55 @@ interface SecurityRequirementObject {
 
 /**
  * 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
  */
 declare function isSSEStream(operation: OperationObject): boolean;
 /**
- * Extracts SSE event types from operation description
+ * Information about an SSE event type including its fields
+ */
+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
  */
 declare function extractSSEEventTypes(operation: OperationObject): string[] | 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
+ */
+declare function extractSSEEventInfo(operation: OperationObject): SSEEventTypeInfo[] | undefined;
 
 interface OpenAPIResponse {
     types: string;
@@ -629,5 +668,5 @@ declare class Bagel {
     uploadFile<T>(file: File, options?: UploadOptions): Promise<T>;
 }
 
-export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, _default as openAPI };
-export type { BaseParameterObject, CallbackObject, CallbacksObject, ComponentsObject, ContactObject, ContentObject, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SSEEvent, SSEStreamOptions, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, StreamEventMap, TableToTypeMapping, Tables, TagObject, TypeFormatT, UploadOptions, User, XmlObject };
+export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventInfo, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, _default as openAPI };
+export type { BaseParameterObject, CallbackObject, CallbacksObject, ComponentsObject, ContactObject, ContentObject, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SSEEvent, SSEEventTypeInfo, SSEStreamOptions, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, StreamEventMap, TableToTypeMapping, Tables, TagObject, TypeFormatT, UploadOptions, User, XmlObject };

package/dist/index.mjs

@@ -1,23 +1,109 @@
 import axios$1 from 'axios';
 
 function isSSEStream(operation) {
-  const description = operation.description?.toLowerCase() || "";
-  const summary = operation.summary?.toLowerCase() || "";
-  const hasSSEKeywords = description.includes("sse") || description.includes("server-sent events") || description.includes("event stream") || summary.includes("stream");
   const responses = operation.responses || {};
-  const hasEventStreamContentType = Object.values(responses).some((response) => {
-    if ("content" in response) {
-      return "text/event-stream" in (response.content || {});
+  for (const [statusCode, response] of Object.entries(responses)) {
+    if (!statusCode.startsWith("2")) continue;
+    if ("$ref" in response) continue;
+    const content = response.content || {};
+    const contentTypes = Object.keys(content);
+    if (contentTypes.length > 0) {
+      if ("text/event-stream" in content) {
+        return true;
+      }
     }
-    return false;
+  }
+  const hasDefinedContentTypes = Object.entries(responses).some(([statusCode, response]) => {
+    if (!statusCode.startsWith("2")) return false;
+    if ("$ref" in response) return false;
+    const content = response.content || {};
+    return Object.keys(content).length > 0;
   });
-  return hasSSEKeywords || hasEventStreamContentType;
+  if (hasDefinedContentTypes) {
+    return false;
+  }
+  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;
 }
 function extractSSEEventTypes(operation) {
   const description = operation.description || "";
+  const types = /* @__PURE__ */ new Set();
+  const markdownMatches = description.matchAll(/^\d+\.\s+\*\*([a-z_]+)\*\*/gm);
+  for (const match of markdownMatches) {
+    types.add(match[1]);
+  }
   const typeMatches = description.matchAll(/type:\s*"([^"]+)"/g);
-  const types = Array.from(typeMatches).map((match) => match[1]);
-  return types.length > 0 ? types : void 0;
+  for (const match of typeMatches) {
+    types.add(match[1]);
+  }
+  const responses = operation.responses || {};
+  for (const response of Object.values(responses)) {
+    if ("content" in response) {
+      const content = response.content || {};
+      const eventStream = content["text/event-stream"];
+      if (eventStream?.example) {
+        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() : void 0;
+}
+function extractSSEEventInfo(operation) {
+  const description = operation.description || "";
+  const eventInfos = [];
+  const eventSections = description.split(/(?=^\d+\.\s+\*\*)/m);
+  for (const section of eventSections) {
+    const eventMatch = section.match(/^\d+\.\s+\*\*([a-z_]+)\*\*:\s*([^\n]+)/m);
+    if (!eventMatch) continue;
+    const [, eventName, eventDescription] = eventMatch;
+    const fields = [];
+    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 : void 0
+    });
+  }
+  if (eventInfos.length === 0) {
+    const responses = operation.responses || {};
+    for (const response of Object.values(responses)) {
+      if ("content" in response) {
+        const content = response.content || {};
+        const eventStream = content["text/event-stream"];
+        if (eventStream?.example) {
+          const exampleMatches = eventStream.example.matchAll(/data:\s*(\{[^}]+\})/g);
+          const seenEvents = /* @__PURE__ */ new Set();
+          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 : void 0
+                });
+              }
+            } catch {
+            }
+          }
+        }
+      }
+    }
+  }
+  return eventInfos.length > 0 ? eventInfos : void 0;
 }
 
 function getPath(pathsObject, path) {
@@ -299,6 +385,7 @@ const primitiveTypes = [
 const functionsInventory = {};
 const pathOperations = [];
 const streamEventTypes = {};
+const streamEventInfo = {};
 function collectTypeForImportStatement(typeName) {
   typeName = typeName.trim().replace("[]", "");
   if (typeName.includes("|")) {
@@ -482,6 +569,7 @@ function generateStreamFunction(method, path, formattedPath, allParams, requestB
   const eventTypesExample = eventTypes?.length ? eventTypes.map((t) => `
    *   .on('${t}', (data) => console.log(data))`).join("") : "\n   *   .on('message', (data) => console.log(data))";
   const typeAnnotation = eventTypes?.length ? `StreamController<${streamTypeName}>` : "StreamController";
+  const pathForUrl = formattedPath.startsWith("`") ? formattedPath.slice(1, -1) : formattedPath.slice(1, -1);
   if (method === "post") {
     return `{
   /**
@@ -496,7 +584,7 @@ function generateStreamFunction(method, path, formattedPath, allParams, requestB
    * stream.close()
    */
   stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
-    const url = \`\${${baseUrlRef}}${formattedPath}\`
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
     return createSSEStreamPost<${streamTypeName}>(url, ${bodyVar}, options)
   },
   /**
@@ -520,7 +608,7 @@ function generateStreamFunction(method, path, formattedPath, allParams, requestB
    * stream.close()
    */
   stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
-    const url = \`\${${baseUrlRef}}${formattedPath}\`
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
     return createSSEStream<${streamTypeName}>(url, options)
   },
   /**
@@ -620,6 +708,11 @@ function generateFunctionForOperation(method, path, operation) {
   const functionComment = buildJSDocComment(operation, method, path);
   if (isStream) {
     const eventTypes = extractSSEEventTypes(operation);
+    const eventInfo = extractSSEEventInfo(operation);
+    const streamTypeName = generateStreamTypeName(path);
+    if (eventInfo?.length) {
+      streamEventInfo[streamTypeName] = eventInfo;
+    }
     return functionComment + generateStreamFunction(
       method,
       path,
@@ -732,19 +825,60 @@ function generateStreamEventTypeDefinitions() {
   typeDefs += "// Stream Event Type Definitions (Fully Typed!)\n";
   typeDefs += "// ============================================================================\n\n";
   for (const [typeName, events] of Object.entries(streamEventTypes)) {
+    const eventInfo = streamEventInfo[typeName];
     typeDefs += `/**
  * Event types for ${typeName.replace("StreamEvents", "")} stream
 `;
     typeDefs += ` * Events: ${events.map((e) => `"${e}"`).join(", ")}
- */
+`;
+    if (eventInfo?.length) {
+      typeDefs += ` *
+`;
+      for (const info of eventInfo) {
+        typeDefs += ` * - **${info.name}**: ${info.description || "Event data"}
+`;
+      }
+    }
+    typeDefs += ` */
 `;
     typeDefs += `export interface ${typeName} {
 `;
-    for (const event of events) {
-      typeDefs += `  /** ${event} event data */
+    if (eventInfo?.length) {
+      for (const info of eventInfo) {
+        typeDefs += `  /**
+   * ${info.description || info.name}
+`;
+        if (info.fields?.length) {
+          info.fields.forEach((field) => {
+            typeDefs += `   * - \`${field.name}\`: ${field.description || "Field data"}
+`;
+          });
+        }
+        typeDefs += `   */
+`;
+        if (info.fields?.length) {
+          typeDefs += `  ${info.name}: {
+`;
+          for (const field of info.fields) {
+            typeDefs += `    /** ${field.description || field.name} */
+`;
+            typeDefs += `    ${field.name}: any
+`;
+          }
+          typeDefs += `  }
 `;
-      typeDefs += `  ${event}: any // TODO: Define specific type from OpenAPI schema
+        } else {
+          typeDefs += `  ${info.name}: any
 `;
+        }
+      }
+    } else {
+      for (const event of events) {
+        typeDefs += `  /** ${event} event data */
+`;
+        typeDefs += `  ${event}: any
+`;
+      }
     }
     typeDefs += "}\n\n";
   }
@@ -1573,4 +1707,4 @@ class Bagel {
   }
 }
 
-export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, index as openAPI };
+export { Bagel, StreamController, createSSEStream, createSSEStreamPost, dereference, extractSSEEventInfo, extractSSEEventTypes, formatAPIErrorMessage, getPath, isReferenceObject, isSSEStream, isSchemaObject, index as openAPI };

package/package.json

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

package/src/openAPITools/functionGenerator.ts

@@ -3,6 +3,7 @@
 /* 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,
@@ -13,8 +14,7 @@ import type {
 	ReferenceObject,
 	SchemaObject,
 } from './types'
-import { isSSEStream, extractSSEEventTypes } from './streamDetector'
-
+import { isSSEStream, extractSSEEventTypes, extractSSEEventInfo } from './streamDetector'
 import { dereference, isReferenceObject } from './types/utils'
 import {
 	cleanPath,
@@ -63,6 +63,7 @@ export interface PathOperation {
 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
@@ -404,6 +405,12 @@ function generateStreamFunction(
 		? `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 `{
   /**
@@ -418,7 +425,7 @@ function generateStreamFunction(
    * stream.close()
    */
   stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
-    const url = \`\${${baseUrlRef}}${formattedPath}\`
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
     return createSSEStreamPost<${streamTypeName}>(url, ${bodyVar}, options)
   },
   /**
@@ -442,7 +449,7 @@ function generateStreamFunction(
    * stream.close()
    */
   stream: (${allParams}, options?: SSEStreamOptions): ${typeAnnotation} => {
-    const url = \`\${${baseUrlRef}}${formattedPath}\`
+    const url = \`\${${baseUrlRef}}${pathForUrl}\`
     return createSSEStream<${streamTypeName}>(url, options)
   },
   /**
@@ -615,6 +622,14 @@ function generateFunctionForOperation(
 	// 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,
@@ -801,6 +816,7 @@ export const ${parent} = ${JSON.stringify(object, undefined, 2)};\n`
 
 /**
  * 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 {
@@ -813,13 +829,53 @@ function generateStreamEventTypeDefinitions(): string {
 	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 */\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`
 
-		for (const event of events) {
-			typeDefs += `  /** ${event} event data */\n`
-			typeDefs += `  ${event}: any // TODO: Define specific type from OpenAPI schema\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'

package/src/openAPITools/streamDetector.ts

@@ -2,43 +2,206 @@ 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 description = operation.description?.toLowerCase() || ''
-	const summary = operation.summary?.toLowerCase() || ''
+	const responses = operation.responses || {}
 
-	// Check for SSE indicators in description or summary
-	const hasSSEKeywords
-		= description.includes('sse')
-			|| description.includes('server-sent events')
-			|| description.includes('event stream')
-			|| summary.includes('stream')
+	// 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
 
-	// Check for text/event-stream content type in responses
-	const responses = operation.responses || {}
-	const hasEventStreamContentType = Object.values(responses).some((response: any) => {
-		if ('content' in response) {
-			return 'text/event-stream' in (response.content || {})
+		// 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
+			}
 		}
-		return false
+	}
+
+	// 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
 	})
 
-	return hasSSEKeywords || hasEventStreamContentType
+	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
+ * 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>()
 
-	// Look for patterns like: type: "token", type: "done", etc.
+	// 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)
-	const types = Array.from(typeMatches).map(match => match[1])
+	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 types.length > 0 ? types : undefined
+	return eventInfos.length > 0 ? eventInfos : undefined
 }