@karpeleslab/klbfw 0.2.23 → 0.2.24

package/index.d.ts

@@ -29,9 +29,152 @@ 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>;
+
+/** 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 {
@@ -189,6 +332,13 @@ export {
   uploadManyFiles,
   getI18N,
   trimPrefix,
+  RestPaging,
+  RestResponse,
+  RestError,
+  DateTime,
+  Xint,
+  PriceValue,
+  Price,
   UploadFileInput,
   UploadFileOptions,
   UploadManyFilesOptions,

package/package.json

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