@bagelink/sdk 1.20.52 → 1.20.56

package/src/openAPITools/index.js

@@ -0,0 +1,40 @@
+import axios from 'axios';
+import { generateFunctions } from './functionGenerator';
+import { generateTypes } from './typeGenerator';
+const basicAuthHeader = { Authorization: 'Basic YmFnZWxfdXNlcm5hbWU6Tm90U2VjdXJlQGJhZ2Vs' };
+export default async (openApiUrl, baseUrl) => {
+    try {
+        console.log(`Fetching OpenAPI spec from: ${openApiUrl}`);
+        const { data: openApi } = await axios.get(openApiUrl, { headers: basicAuthHeader });
+        const schemas = openApi.components?.schemas;
+        if (!schemas) {
+            throw new Error('No schemas found in OpenAPI document');
+        }
+        const types = generateTypes(schemas);
+        // Generate Functions
+        const { paths } = openApi;
+        if (!paths) {
+            throw new Error('No paths found in OpenAPI document');
+        }
+        const code = generateFunctions(paths, baseUrl); // TODO baseURL should not be set here, but should be instatiated in runtime somehow
+        return { types, code };
+    }
+    catch (error) {
+        if (error.response) {
+            // Server responded with error status
+            throw new Error(`HTTP ${error.response.status}: ${error.response.statusText} - Failed to fetch OpenAPI spec from ${openApiUrl}`);
+        }
+        else if (error.request) {
+            // Request was made but no response received
+            throw new Error(`Unable to connect to ${openApiUrl}. Is the server running and accessible?`);
+        }
+        else {
+            // Something else went wrong
+            throw new Error(`Error fetching OpenAPI spec: ${error.message}`);
+        }
+    }
+};
+export * from './streamClient';
+export * from './streamDetector';
+export * from './moduleGenerator';
+export * from './types';

package/src/openAPITools/moduleGenerator.js

@@ -0,0 +1,125 @@
+import { generateModuleFunctions } from './functionGenerator';
+import { generateTypes } from './typeGenerator';
+import { formatType } from './utils';
+const METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+function isReference(value) {
+    return Boolean(value && typeof value === 'object' && '$ref' in value);
+}
+function operationOwners(path, operation, manifest) {
+    return manifest.modules.filter(module => module.pathPrefixes?.some(prefix => path === prefix || path.startsWith(`${prefix}/`))
+        || operation.tags?.some(tag => module.tags?.includes(tag)));
+}
+function collectSchemaRefs(value, refs) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (isReference(value) && value.$ref.startsWith('#/components/schemas/')) {
+        refs.add(value.$ref.slice('#/components/schemas/'.length));
+    }
+    for (const child of Object.values(value))
+        collectSchemaRefs(child, refs);
+}
+function schemaClosure(openApi, seed) {
+    const schemas = openApi.components?.schemas ?? {};
+    const result = new Set(seed);
+    const pending = [...result];
+    while (pending.length) {
+        const name = pending.pop();
+        const schema = schemas[name];
+        if (!schema)
+            continue;
+        const refs = new Set();
+        collectSchemaRefs(schema, refs);
+        for (const ref of refs) {
+            if (!result.has(ref)) {
+                result.add(ref);
+                pending.push(ref);
+            }
+        }
+    }
+    return [...result].sort();
+}
+function moduleFactoryName(name) {
+    return `create${name
+        .split('-')
+        .filter(Boolean)
+        .map(part => part[0].toUpperCase() + part.slice(1))
+        .join('')}Api`;
+}
+export function validateOwnershipManifest(openApi, manifest) {
+    const issues = [];
+    if (manifest.version !== 1) {
+        issues.push({ kind: 'invalid-manifest', message: `Unsupported manifest version: ${manifest.version}` });
+    }
+    const names = manifest.modules.map(module => module.name);
+    for (const name of new Set(names.filter((name, index) => names.indexOf(name) !== index))) {
+        issues.push({ kind: 'invalid-manifest', message: `Duplicate module name: ${name}` });
+    }
+    const schemas = openApi.components?.schemas ?? {};
+    for (const module of manifest.modules) {
+        if (!module.name || !/^[a-z][a-z0-9-]*$/.test(module.name)) {
+            issues.push({ kind: 'invalid-manifest', message: `Invalid module name: ${module.name || '(empty)'}` });
+        }
+        if (!(module.tags?.length || module.pathPrefixes?.length)) {
+            issues.push({ kind: 'invalid-manifest', message: `Module ${module.name} must own tags or pathPrefixes` });
+        }
+        for (const schema of module.schemas ?? []) {
+            if (!schemas[schema])
+                issues.push({ kind: 'unknown-schema', message: `Module ${module.name} owns unknown schema ${schema}` });
+        }
+    }
+    for (const [path, item] of Object.entries(openApi.paths ?? {})) {
+        for (const method of METHODS) {
+            const operation = item[method];
+            if (!operation)
+                continue;
+            const owners = operationOwners(path, operation, manifest);
+            if (owners.length === 0) {
+                issues.push({ kind: 'unowned-operation', message: `${method.toUpperCase()} ${path} is not owned` });
+            }
+            else if (owners.length > 1) {
+                issues.push({
+                    kind: 'multiply-owned-operation',
+                    message: `${method.toUpperCase()} ${path} is owned by ${owners.map(owner => owner.name).join(', ')}`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+export function generateModules(openApi, manifest, baseUrl) {
+    const issues = validateOwnershipManifest(openApi, manifest);
+    if (issues.length)
+        throw new Error(issues.map(issue => issue.message).join('\n'));
+    const schemas = openApi.components?.schemas ?? {};
+    return [...manifest.modules]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((module) => {
+        const paths = {};
+        const refs = new Set(module.schemas ?? []);
+        for (const [path, item] of Object.entries(openApi.paths ?? {})) {
+            const ownedItem = {};
+            for (const method of METHODS) {
+                const operation = item[method];
+                if (operation && operationOwners(path, operation, manifest)[0]?.name === module.name) {
+                    ;
+                    ownedItem[method] = operation;
+                    collectSchemaRefs(operation, refs);
+                }
+            }
+            if (Object.keys(ownedItem).length) {
+                if (item.parameters)
+                    ownedItem.parameters = item.parameters;
+                paths[path] = ownedItem;
+            }
+        }
+        const ownedSchemas = schemaClosure(openApi, refs);
+        const subset = Object.fromEntries(ownedSchemas.map(name => [name, schemas[name]]).filter((entry) => Boolean(entry[1])));
+        return {
+            name: module.name,
+            paths: Object.keys(paths).sort(),
+            schemas: ownedSchemas.map(formatType),
+            code: generateModuleFunctions(paths, baseUrl, moduleFactoryName(module.name)),
+            types: generateTypes(subset),
+        };
+    });
+}

package/src/openAPITools/streamClient.js

@@ -0,0 +1,276 @@
+/**
+ * SSE (Server-Sent Events) Client Utilities
+ * Simple, reliable SSE streaming without event loss
+ */
+import { StreamController } from './StreamController';
+export { StreamController } from './StreamController';
+async function resolveHeaders(headers) {
+    return typeof headers === 'function' ? await headers() : (headers ?? {});
+}
+/**
+ * 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(url, options = {}) {
+    const { headers, withCredentials = true, lastEventId: initialLastEventId, maxReconnects = 5, reconnectDelayMs = 1000, } = options;
+    const controller = new AbortController();
+    const stream = new StreamController(() => { controller.abort(); });
+    let lastEventId = initialLastEventId;
+    let reconnectAttempts = 0;
+    async function connect() {
+        if (controller.signal.aborted)
+            return;
+        const resolvedHeaders = await resolveHeaders(headers);
+        const requestHeaders = {
+            'Accept': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            ...resolvedHeaders,
+        };
+        if (lastEventId !== undefined) {
+            requestHeaders['Last-Event-ID'] = lastEventId;
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'GET',
+                headers: requestHeaders,
+                credentials: withCredentials ? 'include' : 'same-origin',
+                signal: controller.signal,
+                keepalive: false,
+            });
+        }
+        catch (error) {
+            if (error?.name === 'AbortError')
+                return;
+            return handleDisconnect(error);
+        }
+        if (!response.ok) {
+            stream.emit('error', new Error(`HTTP ${response.status}: ${response.statusText}`));
+            return;
+        }
+        if (!response.body) {
+            stream.emit('error', new Error('Response body is null'));
+            return;
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let terminalEventReceived = false;
+        // SSE parser state MUST live across read() chunks: a single event's
+        // `event:`/`data:` lines and its terminating blank line can be split over
+        // multiple network chunks (very common for large payloads such as big
+        // tool_result blobs). Re-initialising these per chunk would drop or
+        // mis-attribute those events, making large results appear to only "arrive"
+        // once the whole response flushes at the end.
+        let currentEvent = 'message';
+        let currentData = '';
+        let currentId;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    if (!controller.signal.aborted && !terminalEventReceived) {
+                        return handleDisconnect(new Error('Stream ended before a terminal event'));
+                    }
+                    return;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (line.startsWith('id:')) {
+                        currentId = line.slice(3).trim();
+                    }
+                    else if (line.startsWith('event:')) {
+                        currentEvent = line.slice(6).trim();
+                    }
+                    else if (line.startsWith('data:')) {
+                        // Accumulate multi-line data fields per the SSE spec instead of
+                        // overwriting, so multi-line `data:` payloads survive intact.
+                        currentData = currentData ? `${currentData}\n${line.slice(5).trim()}` : line.slice(5).trim();
+                    }
+                    else if (line === '' && currentData) {
+                        // Track last seen ID for reconnect
+                        if (currentId !== undefined) {
+                            if (currentId !== lastEventId)
+                                reconnectAttempts = 0;
+                            lastEventId = currentId;
+                        }
+                        try {
+                            const parsed = JSON.parse(currentData);
+                            stream.emit(currentEvent, parsed);
+                            // Auto-close stream on terminal events
+                            if (currentEvent === 'done' || currentEvent === 'error') {
+                                terminalEventReceived = true;
+                                stream.emit('complete', {});
+                                controller.abort();
+                                try {
+                                    await reader.cancel();
+                                }
+                                catch { /* already closed */ }
+                                return;
+                            }
+                        }
+                        catch {
+                            stream.emit(currentEvent, currentData);
+                        }
+                        currentEvent = 'message';
+                        currentData = '';
+                        currentId = undefined;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error?.name !== 'AbortError') {
+                return handleDisconnect(error);
+            }
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    async function handleDisconnect(error) {
+        if (controller.signal.aborted)
+            return;
+        if (reconnectAttempts >= maxReconnects) {
+            const msg = error?.message || 'Stream connection lost';
+            stream.emit('error', new Error(`${msg} (gave up after ${maxReconnects} reconnects)`));
+            return;
+        }
+        reconnectAttempts++;
+        const delay = reconnectDelayMs * Math.pow(2, reconnectAttempts - 1); // exponential backoff
+        await new Promise(resolve => setTimeout(resolve, delay));
+        if (!controller.signal.aborted)
+            await connect();
+    }
+    connect().catch(() => { });
+    return stream;
+}
+/**
+ * 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(url, body, options = {}) {
+    const { headers, withCredentials = true } = options;
+    const controller = new AbortController();
+    const stream = new StreamController(() => { controller.abort(); });
+    // Resolve headers inside the request so async auth providers work for SSE too.
+    resolveHeaders(headers)
+        .then(resolvedHeaders => fetch(url, {
+        method: 'POST',
+        headers: {
+            'Accept': 'text/event-stream',
+            'Content-Type': 'application/json',
+            'Cache-Control': 'no-cache',
+            ...resolvedHeaders,
+        },
+        credentials: withCredentials ? 'include' : 'same-origin',
+        body: JSON.stringify(body),
+        signal: controller.signal,
+        // Disable keepalive for streaming
+        keepalive: false,
+    }))
+        .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 = '';
+        // Parser state must persist across chunks — a single SSE event (esp. a
+        // large tool_result) can be split over multiple network reads.
+        let currentEvent = 'message';
+        let currentData = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    stream.emit('done', {});
+                    stream.emit('complete', {});
+                    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
+                for (const line of lines) {
+                    if (line.startsWith('event:')) {
+                        currentEvent = line.slice(6).trim();
+                    }
+                    else if (line.startsWith('data:')) {
+                        currentData = currentData ? `${currentData}\n${line.slice(5).trim()}` : line.slice(5).trim();
+                    }
+                    else if (line === '' && currentData) {
+                        // Empty line indicates end of event - emit immediately
+                        try {
+                            const parsed = JSON.parse(currentData);
+                            stream.emit(currentEvent, parsed);
+                        }
+                        catch {
+                            // If not valid JSON, emit as string
+                            stream.emit(currentEvent, currentData);
+                        }
+                        // Reset for next event
+                        currentEvent = 'message';
+                        currentData = '';
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Handle all stream errors (network errors, protocol errors, etc.)
+            if (error?.name !== 'AbortError') {
+                const errorMessage = error?.message || 'Stream connection error';
+                stream.emit('error', new Error(errorMessage));
+            }
+        }
+        finally {
+            // Clean up reader
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    })
+        .catch((error) => {
+        if (error?.name !== 'AbortError') {
+            const errorMessage = error?.message || 'Failed to establish stream connection';
+            stream.emit('error', new Error(errorMessage));
+        }
+    });
+    return stream;
+}

package/src/openAPITools/streamDetector.js

@@ -0,0 +1,204 @@
+/**
+ * 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) {
+    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.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.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;
+}
+/**
+ * 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) {
+    const description = operation.description || '';
+    const types = new Set();
+    // 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.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 typed schema refs from the x-event-schemas OpenAPI extension.
+ *
+ * Server sets this via sse_openapi_response(event_types={"created": MyModel}).
+ * Returns a map of { event_name: TypeScript type name } derived from the $ref,
+ * e.g. { "connection_created": "ConferenceConnectionOut" }.
+ *
+ * @param operation - The OpenAPI operation object
+ * @returns Map of event name → TS type name, or undefined if not present
+ */
+export function extractSSEEventSchemas(operation) {
+    const responses = operation.responses || {};
+    for (const [statusCode, response] of Object.entries(responses)) {
+        if (!statusCode.startsWith('2'))
+            continue;
+        if ('$ref' in response)
+            continue;
+        const eventStream = response.content?.['text/event-stream'];
+        const schemas = eventStream?.['x-event-schemas'];
+        if (schemas && Object.keys(schemas).length > 0) {
+            // Convert $ref paths like "#/components/schemas/MyModel" → "MyModel"
+            return Object.fromEntries(Object.entries(schemas).map(([event, ref]) => [
+                event,
+                ref.replace(/^#\/components\/schemas\//, ''),
+            ]));
+        }
+    }
+    return 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) {
+    const description = operation.description || '';
+    const eventInfos = [];
+    // 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 = [];
+        const fieldMatches = section.matchAll(/^\s+[-*]\s+`([^`]+)`:\s*([^\n]+)/gm);
+        for (const fieldMatch of fieldMatches) {
+            let [, fieldName, fieldDescription] = fieldMatch;
+            // Handle nested field names like "error.code" → extract just "code"
+            // This handles documentation that shows nested object paths
+            if (fieldName.includes('.')) {
+                const parts = fieldName.split('.');
+                fieldName = parts[parts.length - 1]; // Take the last part
+            }
+            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.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();
+                    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;
+}