@vicaniddouglas/js_aide 1.10.0 → 1.12.0

package/README.md

@@ -230,13 +230,32 @@ Every call returns a Promise that always resolves to this structure:
 #### New Proactive Options
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `onSuccess` | `Function` | `null` | Runs automatically if `status` is `true`. |
-| `onError` | `Function` | `null` | Runs automatically if `status` is `false`. |
+| `onSuccess` | `Function` | `null` | Runs automatically if `status` is `true`. **Strictly awaited.** |
+| `onError` | `Function` | `null` | Runs automatically if `status` is `false`. **Strictly awaited.** |
+| `showLoading` | `Function` | `null` | Called with `true`/`false`. **Strictly awaited.** |
 | `silent` | `Boolean` | `false` | If `true`, disables the automatic Red Popup on error. |
 
 #### Usage Patterns
 
-**1. The "Fire and Forget" (Proactive Success)**
+**1. The "Sequential Async Flow" (Awaiting Callbacks)**
+Because `sendRequest` **strictly awaits** your callbacks, you can safely use `async/await` inside them without worrying about race conditions or premature page reloads.
+```javascript
+import { sendRequest, popup } from "@vicaniddouglas/js_aide";
+
+await sendRequest({
+  endpoint: '/api/save',
+  onSuccess: async (data) => {
+    // This popup is BEAUTIFUL and BLOCKING.
+    // sendRequest will NOT finish until the user clicks OK.
+    await popup.success("Settings Saved!"); 
+  }
+});
+
+// This reload is GUARANTEED to happen only after the popup is closed.
+window.location.reload(); 
+```
+
+**2. The "Fire and Forget" (Proactive Success)**
 No need to check status if you only care about success. If it fails, the user gets a popup automatically.
 ```javascript
 import { sendRequest } from "@vicaniddouglas/js_aide";

package/declarations.d.ts

@@ -313,7 +313,10 @@ declare module "@vicaniddouglas/js_aide" {
     useQueue?: boolean;
     priority?: number;
     responseType?: "json" | "text";
-    showLoading?: (isLoading: boolean) => void;
+    showLoading?: (isLoading: boolean) => void | Promise<void>;
+    onSuccess?: (data: any) => void | Promise<void>;
+    onError?: (log: string) => void | Promise<void>;
+    silent?: boolean;
   }
 
   type RequestInterceptor = (
@@ -337,7 +340,16 @@ declare module "@vicaniddouglas/js_aide" {
     pending: number;
   }
 
-  export const sendRequest: (options?: RequestOptions) => Promise<any>;
+  interface StandardizedResponse {
+    status: boolean;
+    log: string;
+    data: any;
+    httpCode: number;
+  }
+
+  export const sendRequest: (
+    options?: RequestOptions,
+  ) => Promise<StandardizedResponse>;
   export const initRequestHandler: (options?: RequestHandlerConfig) => void;
   export const interceptors: InterceptorMethods;
   export const getQueueStatus: () => QueueStatus;
@@ -1222,6 +1234,33 @@ declare module "@vicaniddouglas/js_aide" {
     sendIcon2(): string;
   };
 
+  // =========================================================
+  // popup (from popup.js)
+  // =========================================================
+  interface PopupOptions {
+    /** Time before auto-close (ms) */
+    duration?: number;
+    /** Stay on screen until manually closed */
+    persistent?: boolean;
+    /** Show close button and enable Esc/Backdrop clicks */
+    closable?: boolean;
+    /** Custom SVG string to override default icon */
+    icon?: string;
+    /** Custom CSS color for icon and background tint */
+    color?: string;
+  }
+
+  export const popup: {
+    /** Show a success modal (Green theme) */
+    success(message: string, options?: PopupOptions): Promise<void>;
+    /** Show an error modal (Red theme) */
+    error(message: string, options?: PopupOptions): Promise<void>;
+    /** Show an info modal (Blue theme) */
+    info(message: string, options?: PopupOptions): Promise<void>;
+    /** Programmatically close the current modal */
+    close(): void;
+  };
+
   //============================================================================
   // app loader to render different views
   //============================================================================