@karpeleslab/klbfw 0.2.21 → 0.2.23

package/README.md

@@ -50,6 +50,48 @@ npm run test:integration
 - **Standardized Naming**: Consistent use of camelCase with backward compatibility for legacy APIs
 - **Enhanced Error Handling**: More robust error handling and reporting
 
+## Migrating from upload.append() to uploadFile()
+
+The new `uploadFile()` function provides a simpler Promise-based API for file uploads. Here are the key differences when migrating:
+
+### Return Value
+
+**Legacy `upload.append()`** resolves with an upload object containing the result in `.final`:
+```javascript
+upload.append('Misc/Debug:testUpload', file)
+  .then(result => {
+    console.log(result.final);  // The completion response data
+  });
+```
+
+**New `uploadFile()`** resolves with the full REST response:
+```javascript
+uploadFile('Misc/Debug:testUpload', buffer)
+  .then(response => {
+    console.log(response.data);  // The completion response data
+  });
+```
+
+### Migration Example
+
+Before:
+```javascript
+upload.append('Misc/Debug:testUpload', file, params, context)
+  .then(up => {
+    const data = up.final;
+    // use data
+  });
+```
+
+After:
+```javascript
+uploadFile('Misc/Debug:testUpload', file, 'POST', params, context)
+  .then(response => {
+    const data = response.data;
+    // use data
+  });
+```
+
 # API
 
 ## REST API Methods

package/index.d.ts

@@ -32,7 +32,50 @@ declare function setCookie(name: string, value: string, expires?: Date | number,
 declare function rest(name: string, verb: string, params?: Record<string, any>, context?: Record<string, any>): Promise<any>;
 declare function rest_get(name: string, params?: Record<string, any>): Promise<any>; // Backward compatibility
 declare function restGet(name: string, params?: Record<string, any>): Promise<any>;
-declare function restSSE(name: string, method: 'GET', params?: Record<string, any>, context?: Record<string, any>): EventSource;
+
+/** SSE message event */
+interface SSEMessageEvent {
+  /** Event type */
+  type: string;
+  /** Event data */
+  data: string;
+  /** Last event ID */
+  lastEventId: string;
+  /** Origin */
+  origin: string;
+}
+
+/** SSE error event */
+interface SSEErrorEvent {
+  type: 'error';
+  error: Error | Record<string, any>;
+}
+
+/** EventSource-like object returned by restSSE */
+interface SSESource {
+  /** Handler called when connection opens */
+  onopen: ((event: { type: 'open' }) => void) | null;
+  /** Handler called for message events */
+  onmessage: ((event: SSEMessageEvent) => void) | null;
+  /** Handler called on error */
+  onerror: ((event: SSEErrorEvent) => void) | null;
+  /** Connection state: 0 = CONNECTING, 1 = OPEN, 2 = CLOSED */
+  readyState: number;
+  /** CONNECTING state constant */
+  readonly CONNECTING: 0;
+  /** OPEN state constant */
+  readonly OPEN: 1;
+  /** CLOSED state constant */
+  readonly CLOSED: 2;
+  /** Add event listener for specific event type */
+  addEventListener(type: string, listener: (event: SSEMessageEvent) => void): void;
+  /** Remove event listener */
+  removeEventListener(type: string, listener: (event: SSEMessageEvent) => void): void;
+  /** Close the connection */
+  close(): void;
+}
+
+declare function restSSE(name: string, method?: string, params?: Record<string, any>, context?: Record<string, any>): SSESource;
 
 // Upload module types
 
@@ -90,7 +133,7 @@ declare const upload: {
   onprogress?: (status: { queue: any[]; running: any[]; failed: any[] }) => void;
 };
 
-/** Upload a single file */
+/** Upload a single file. Resolves with the full REST response. */
 declare function uploadFile(
   api: string,
   buffer: UploadFileInput,
@@ -148,5 +191,8 @@ export {
   trimPrefix,
   UploadFileInput,
   UploadFileOptions,
-  UploadManyFilesOptions
+  UploadManyFilesOptions,
+  SSEMessageEvent,
+  SSEErrorEvent,
+  SSESource
 };

package/internal.js

@@ -344,4 +344,5 @@ module.exports.responseParse = responseParse;
 module.exports.padNumber = padNumber;
 module.exports.getTimezoneData = getTimezoneData;
 module.exports.buildRestUrl = buildRestUrl;
-module.exports.internalRest = internalRest;
+module.exports.internalRest = internalRest;
+module.exports.checkAndRefreshToken = checkAndRefreshToken;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karpeleslab/klbfw",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Frontend Framework",
   "main": "index.js",
   "types": "index.d.ts",

package/rest.js

@@ -154,62 +154,359 @@ const restGet = (name, params) => {
 };
 
 /**
- * Creates a Server-Sent Events (SSE) connection to a REST API endpoint
+ * Parses a single SSE event from text
+ * @param {string} eventText - The raw SSE event text
+ * @returns {Object} Parsed event object with type, data, id, and retry fields
+ */
+const parseSSEEvent = (eventText) => {
+    const event = {
+        type: 'message',
+        data: '',
+        id: null,
+        retry: null
+    };
+
+    const lines = eventText.split('\n');
+    const dataLines = [];
+
+    for (const line of lines) {
+        if (line === '') continue;
+
+        // Handle lines with field:value format
+        const colonIndex = line.indexOf(':');
+
+        if (colonIndex === 0) {
+            // Comment line (starts with :), skip
+            continue;
+        }
+
+        let field, value;
+        if (colonIndex === -1) {
+            // Field with no value
+            field = line;
+            value = '';
+        } else {
+            field = line.substring(0, colonIndex);
+            // Skip the optional space after colon
+            value = line.substring(colonIndex + 1);
+            if (value.charAt(0) === ' ') {
+                value = value.substring(1);
+            }
+        }
+
+        switch (field) {
+            case 'event':
+                event.type = value;
+                break;
+            case 'data':
+                dataLines.push(value);
+                break;
+            case 'id':
+                event.id = value;
+                break;
+            case 'retry':
+                const retryMs = parseInt(value, 10);
+                if (!isNaN(retryMs)) {
+                    event.retry = retryMs;
+                }
+                break;
+        }
+    }
+
+    // Join data lines with newlines (per SSE spec)
+    event.data = dataLines.join('\n');
+
+    return event;
+};
+
+/**
+ * Makes a REST API request that handles SSE streaming responses
  * @param {string} name - API endpoint name
- * @param {string} method - HTTP method (must be GET)
+ * @param {string} method - HTTP method (GET, POST, etc.)
  * @param {Object} params - Request parameters
- * @param {Object} context - Context object with additional parameters
- * @returns {EventSource} EventSource instance for the SSE connection
+ * @param {Object} [context] - Context object with additional parameters
+ * @returns {Object} EventSource-like object with onmessage, onerror, addEventListener, close
  */
 const restSSE = (name, method, params, context) => {
-    // EventSource only supports GET requests
-    if (method !== 'GET') {
-        throw new Error('EventSource only supports GET method');
-    }
+    const abortController = new AbortController();
 
-    // EventSource only works in browsers
-    if (typeof EventSource === 'undefined') {
-        throw new Error('EventSource is not supported in this environment');
-    }
+    method = method || 'GET';
+    params = params || {};
+    context = context || {};
+
+    // EventSource-like object
+    const eventSource = {
+        onopen: null,
+        onmessage: null,
+        onerror: null,
+        readyState: 0, // 0 = CONNECTING, 1 = OPEN, 2 = CLOSED
+        CONNECTING: 0,
+        OPEN: 1,
+        CLOSED: 2,
+        _listeners: {},
+
+        addEventListener: function(type, listener) {
+            if (!this._listeners[type]) {
+                this._listeners[type] = [];
+            }
+            this._listeners[type].push(listener);
+        },
+
+        removeEventListener: function(type, listener) {
+            if (!this._listeners[type]) return;
+            const idx = this._listeners[type].indexOf(listener);
+            if (idx !== -1) {
+                this._listeners[type].splice(idx, 1);
+            }
+        },
+
+        dispatchEvent: function(event) {
+            // Call type-specific handler (onmessage, onerror, etc.)
+            const handlerName = 'on' + event.type;
+            if (typeof this[handlerName] === 'function') {
+                this[handlerName](event);
+            }
+
+            // Call addEventListener listeners
+            const listeners = this._listeners[event.type];
+            if (listeners) {
+                for (const listener of listeners) {
+                    listener(event);
+                }
+            }
+        },
+
+        close: function() {
+            this.readyState = 2;
+            abortController.abort();
+        }
+    };
 
     if (!internal.checkSupport()) {
-        throw new Error('Environment not supported');
+        setTimeout(() => {
+            eventSource.readyState = 2;
+            eventSource.dispatchEvent({ type: 'error', error: new Error('Environment not supported') });
+        }, 0);
+        return eventSource;
     }
 
-    params = params || {};
-    context = context || {};
-
     // Add timezone data if in browser
     if (typeof window !== 'undefined') {
         context['t'] = internal.getTimezoneData();
     }
 
-    // Build URL with authentication and context
     let callUrl = internal.buildRestUrl(name, true, context);
+    const headers = {
+        'Accept': 'text/event-stream, application/json'
+    };
 
-    // Add params to the URL
-    if (params) {
-        const glue = callUrl.indexOf('?') === -1 ? '?' : '&';
-        if (typeof params === 'string') {
-            callUrl += glue + '_=' + encodeURIComponent(params);
-        } else {
-            callUrl += glue + '_=' + encodeURIComponent(JSON.stringify(params));
+    const token = fwWrapper.getToken();
+    if (token && token !== '') {
+        headers['Authorization'] = 'Session ' + token;
+    }
+
+    // Build fetch options based on method
+    const fetchOptions = {
+        method: method,
+        credentials: 'include',
+        headers: headers,
+        signal: abortController.signal
+    };
+
+    if (method === 'GET') {
+        // For GET requests, add params to URL
+        if (params && Object.keys(params).length > 0) {
+            const glue = callUrl.indexOf('?') === -1 ? '?' : '&';
+            if (typeof params === 'string') {
+                callUrl += glue + '_=' + encodeURIComponent(params);
+            } else {
+                callUrl += glue + '_=' + encodeURIComponent(JSON.stringify(params));
+            }
         }
+    } else {
+        // For other methods, add params to body as JSON
+        headers['Content-Type'] = 'application/json; charset=utf-8';
+        fetchOptions.body = JSON.stringify(params);
     }
 
-    // Create and return EventSource instance
-    // Note: EventSource doesn't support custom headers directly,
-    // but authentication is handled via URL parameters or cookies
-    const eventSource = new EventSource(callUrl, {
-        withCredentials: true
-    });
+    // Helper to dispatch SSE events
+    const dispatchSSEEvent = (parsedEvent) => {
+        const event = {
+            type: parsedEvent.type,
+            data: parsedEvent.data,
+            lastEventId: parsedEvent.id || '',
+            origin: ''
+        };
 
-    // Handle errors and server-side closures
-    eventSource.onerror = (error) => {
-        console.error('EventSource error:', error);
-        eventSource.close();
+        // For 'message' type, use onmessage
+        if (parsedEvent.type === 'message') {
+            eventSource.dispatchEvent(event);
+        } else {
+            // For custom event types, dispatch to both the specific type and as a generic event
+            eventSource.dispatchEvent(event);
+        }
     };
 
+    // Check and refresh token if needed, then make the request
+    internal.checkAndRefreshToken().then(() => {
+        fetch(callUrl, fetchOptions)
+        .then(response => {
+            if (!response.ok) {
+                // Handle HTTP errors
+                const contentType = response.headers.get('content-type') || '';
+                if (contentType.indexOf('application/json') !== -1) {
+                    return response.json().then(json => {
+                        json.headers = response.headers;
+                        json.status = response.status;
+                        throw json;
+                    });
+                }
+                throw {
+                    message: `HTTP Error: ${response.status} ${response.statusText}`,
+                    status: response.status,
+                    headers: response.headers
+                };
+            }
+
+            // Connection is now open
+            eventSource.readyState = 1;
+            eventSource.dispatchEvent({ type: 'open' });
+
+            const contentType = response.headers.get('content-type') || '';
+
+            // Check if response is SSE
+            if (contentType.indexOf('text/event-stream') !== -1) {
+                // Stream SSE events
+                let buffer = '';
+
+                const processData = (chunk) => {
+                    buffer += chunk;
+
+                    // SSE events are separated by double newlines
+                    const events = buffer.split(/\n\n/);
+
+                    // Keep the last incomplete event in the buffer
+                    buffer = events.pop() || '';
+
+                    // Process complete events
+                    for (const eventText of events) {
+                        if (eventText.trim()) {
+                            const parsed = parseSSEEvent(eventText);
+                            if (parsed.data || parsed.type !== 'message') {
+                                dispatchSSEEvent(parsed);
+                            }
+                        }
+                    }
+                };
+
+                const processEnd = () => {
+                    // Process any remaining data in buffer
+                    if (buffer.trim()) {
+                        const parsed = parseSSEEvent(buffer);
+                        if (parsed.data || parsed.type !== 'message') {
+                            dispatchSSEEvent(parsed);
+                        }
+                    }
+                    eventSource.readyState = 2;
+                };
+
+                // Check if we have a web ReadableStream (browser) or Node.js stream
+                if (response.body && typeof response.body.getReader === 'function') {
+                    // Browser environment - use ReadableStream API
+                    const reader = response.body.getReader();
+                    const decoder = new TextDecoder();
+
+                    const processStream = () => {
+                        reader.read().then(({ done, value }) => {
+                            if (done) {
+                                processEnd();
+                                return;
+                            }
+
+                            processData(decoder.decode(value, { stream: true }));
+
+                            // Continue reading
+                            processStream();
+                        }).catch(err => {
+                            if (err.name !== 'AbortError') {
+                                eventSource.dispatchEvent({ type: 'error', error: err });
+                            }
+                            eventSource.readyState = 2;
+                        });
+                    };
+
+                    processStream();
+                } else if (response.body && typeof response.body.on === 'function') {
+                    // Node.js environment - use Node stream API
+                    response.body.on('data', (chunk) => {
+                        processData(chunk.toString());
+                    });
+
+                    response.body.on('end', () => {
+                        processEnd();
+                    });
+
+                    response.body.on('error', (err) => {
+                        // Handle abort errors gracefully
+                        if (err.type !== 'aborted' && err.name !== 'AbortError') {
+                            eventSource.dispatchEvent({ type: 'error', error: err });
+                        }
+                        eventSource.readyState = 2;
+                    });
+                } else {
+                    // Fallback - read entire body as text
+                    response.text().then(text => {
+                        processData(text);
+                        processEnd();
+                    }).catch(err => {
+                        eventSource.dispatchEvent({ type: 'error', error: err });
+                        eventSource.readyState = 2;
+                    });
+                }
+            } else if (contentType.indexOf('application/json') !== -1) {
+                // Non-SSE JSON response - emit as single event
+                response.json().then(json => {
+                    // Check for gtag (consistent with responseParse)
+                    if (json.gtag && typeof window !== 'undefined' && window.gtag) {
+                        json.gtag.map(item => window.gtag.apply(null, item));
+                    }
+
+                    dispatchSSEEvent({
+                        type: 'message',
+                        data: JSON.stringify(json),
+                        id: null
+                    });
+                    eventSource.readyState = 2;
+                }).catch(err => {
+                    eventSource.dispatchEvent({ type: 'error', error: err });
+                    eventSource.readyState = 2;
+                });
+            } else {
+                // Other content types - emit raw text as single event
+                response.text().then(text => {
+                    dispatchSSEEvent({
+                        type: 'message',
+                        data: text,
+                        id: null
+                    });
+                    eventSource.readyState = 2;
+                }).catch(err => {
+                    eventSource.dispatchEvent({ type: 'error', error: err });
+                    eventSource.readyState = 2;
+                });
+            }
+        })
+        .catch(err => {
+            if (err.name !== 'AbortError') {
+                eventSource.dispatchEvent({ type: 'error', error: err });
+            }
+            eventSource.readyState = 2;
+        });
+    }).catch(err => {
+        eventSource.dispatchEvent({ type: 'error', error: err });
+        eventSource.readyState = 2;
+    });
+
     return eventSource;
 };
 

package/upload.js

@@ -37,7 +37,7 @@ const { env, utils, awsReq, readChunkFromStream, readFileSlice } = require('./up
  * @param {Function} [options.onError] - Error callback(error, context). Can return a Promise
  *   that, if resolved, will cause the failed operation to be retried. Context contains
  *   { phase, blockNum, attempt } for block uploads or { phase, attempt } for other operations.
- * @returns {Promise<Object>} - Resolves with the upload result data
+ * @returns {Promise<Object>} - Resolves with the full REST response
  *
  * @example
  * // Upload a buffer with filename
@@ -290,7 +290,7 @@ async function doPutUpload(file, uploadInfo, context, options) {
         attempt++;
         try {
             const completeResponse = await rest.rest(uploadInfo.Complete, 'POST', {}, context);
-            return completeResponse.data;
+            return completeResponse;
         } catch (error) {
             if (onError) {
                 await onError(error, { phase: 'complete', attempt });
@@ -542,7 +542,7 @@ async function doAwsUpload(file, uploadInfo, context, options) {
                 {},
                 context
             );
-            return finalResponse.data;
+            return finalResponse;
         } catch (error) {
             if (onError) {
                 await onError(error, { phase: 'handleComplete', attempt: handleAttempt });