@karpeleslab/klbfw 0.2.22 → 0.2.24

package/index.d.ts

@@ -29,10 +29,196 @@ declare function hasCookie(name: string): boolean;
 declare function setCookie(name: string, value: string, expires?: Date | number, path?: string, domain?: string, secure?: boolean): void;
 
 // REST API types
-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;
+
+/** Paging information returned by list endpoints */
+interface RestPaging {
+  /** Current page number (1-indexed) */
+  page_no: number;
+  /** Total number of results across all pages */
+  count: number;
+  /** Maximum page number available */
+  page_max: number;
+  /** Number of results per page */
+  results_per_page: number;
+}
+
+/**
+ * Successful REST API response wrapper
+ * @typeParam T - Type of the data field
+ */
+interface RestResponse<T = any> {
+  /** Result status */
+  result: 'success' | 'redirect';
+  /** Unique request identifier for debugging */
+  request_id: string;
+  /** Request processing time in seconds */
+  time: number;
+  /** Response payload */
+  data: T;
+  /** Paging information for list endpoints */
+  paging?: RestPaging;
+  /** Additional response fields */
+  [key: string]: any;
+}
+
+/** REST API error object (thrown on promise rejection) */
+interface RestError {
+  /** Always 'error' for error responses */
+  result: 'error';
+  /** Exception class name from server */
+  exception: string;
+  /** Human-readable error message */
+  error: string;
+  /** HTTP status code */
+  code: number;
+  /** Translatable error token (e.g., 'error_invalid_field') */
+  token: string;
+  /** Request ID for debugging */
+  request: string;
+  /** Structured message data for translation */
+  message: Record<string, any>;
+  /** Parameter name that caused the error, if applicable */
+  param?: string;
+  /** Request processing time in seconds */
+  time: number;
+  /** Additional error fields */
+  [key: string]: any;
+}
+
+/**
+ * Server DateTime object
+ * @example
+ * // Convert to JavaScript Date
+ * new Date(Number(datetime.unixms))
+ */
+interface DateTime {
+  /** Unix timestamp in milliseconds (use this for JS Date conversion) */
+  unixms: string | number;
+  /** Unix timestamp in seconds */
+  unix?: number;
+  /** Microseconds component */
+  us?: number;
+  /** ISO 8601 formatted string with microseconds */
+  iso?: string;
+  /** Timezone identifier (e.g., 'Asia/Tokyo') */
+  tz?: string;
+  /** Full precision timestamp as string (unix seconds + microseconds) */
+  full?: string;
+}
+
+/**
+ * Extended integer for precise decimal arithmetic without floating-point errors.
+ * Value = v / 10^e = f
+ *
+ * When sending to API, you can provide either:
+ * - Just `f` (as string or number)
+ * - Both `v` and `e`
+ *
+ * @example
+ * // $358.20 represented as:
+ * { v: "35820000", e: 5, f: 358.2 }
+ */
+interface Xint {
+  /** Integer value (multiply by 10^-e to get actual value) */
+  v?: string;
+  /** Exponent (number of decimal places) */
+  e?: number;
+  /** Float value (convenience field, may have precision loss) */
+  f?: string | number;
+}
+
+/** Base price value without tax breakdown */
+interface PriceValue {
+  /** Decimal value as string (e.g., "358.20000") */
+  value: string;
+  /** Integer representation for precise arithmetic */
+  value_int: string;
+  /** Value in cents/smallest currency unit */
+  value_cent: string;
+  /** Display-ready decimal string (e.g., "358.20") */
+  value_disp: string;
+  /** Extended integer for precise calculations */
+  value_xint: Xint;
+  /** Formatted display string with currency symbol (e.g., "$358.20") */
+  display: string;
+  /** Short formatted display string */
+  display_short: string;
+  /** ISO 4217 currency code (e.g., "USD") */
+  currency: string;
+  /** Currency unit (usually same as currency) */
+  unit: string;
+  /** Whether VAT/tax is included in this value */
+  has_vat: boolean;
+  /** Tax profile identifier or null if exempt */
+  tax_profile: string | null;
+}
+
+/**
+ * Full price object with optional tax breakdown
+ * @example
+ * // Display price with tax info
+ * console.log(price.display);           // "$358.20"
+ * console.log(price.tax?.display);      // "$358.20" (with tax)
+ * console.log(price.tax_only?.display); // "$0.00" (tax amount only)
+ */
+interface Price extends PriceValue {
+  /** Original price before any tax calculations */
+  raw?: PriceValue;
+  /** Price including tax */
+  tax?: PriceValue;
+  /** Tax amount only */
+  tax_only?: PriceValue;
+  /** Tax rate as decimal (e.g., 0.1 for 10%) */
+  tax_rate?: number;
+}
+
+declare function rest<T = any>(name: string, verb: string, params?: Record<string, any>, context?: Record<string, any>): Promise<RestResponse<T>>;
+declare function rest_get<T = any>(name: string, params?: Record<string, any>): Promise<RestResponse<T>>; // Backward compatibility
+declare function restGet<T = any>(name: string, params?: Record<string, any>): Promise<RestResponse<T>>;
+
+/** 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
 
@@ -146,7 +332,17 @@ export {
   uploadManyFiles,
   getI18N,
   trimPrefix,
+  RestPaging,
+  RestResponse,
+  RestError,
+  DateTime,
+  Xint,
+  PriceValue,
+  Price,
   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.22",
+  "version": "0.2.24",
   "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;
 };