@qumra/jisr 1.0.0 → 1.0.1

package/README.md

@@ -1,8 +1,21 @@
 # @qumra/jisr
 
-React hooks and utilities for communicating with the Qumra Admin from embedded apps running in an iframe.
+[![npm version](https://img.shields.io/npm/v/@qumra/jisr.svg)](https://www.npmjs.com/package/@qumra/jisr)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-This package mirrors the functionality of Shopify's `@shopify/app-bridge-react` and provides a seamless integration layer for apps running within the Qumra Admin environment.
+> App Bridge for Qumra embedded apps — React hooks for communicating with the Qumra Admin.
+>
+> **جسر** (Jisr) = Bridge in Arabic
+
+`@qumra/jisr` provides a set of React hooks and utilities for seamless communication between embedded applications (running in iframes) and the Qumra Admin interface via `postMessage`. Perfect for building extensible admin apps that need to interact with the parent Qumra environment.
+
+## Features
+
+- 🌉 **iframe ↔ Admin Communication** — Transparent two-way messaging
+- 🎣 **Custom React Hooks** — `useNavigate`, `useToast`, `useModal`, `useSaveBar`, and more
+- 📘 **TypeScript Support** — Fully typed exports for better DX
+- 🔐 **Authenticated Requests** — Built-in hook for fetch with auth headers
+- ⚡ **Simple Setup** — Wrap your app with `QumraAppBridgeProvider`
 
 ## Installation
 
@@ -10,359 +23,249 @@ This package mirrors the functionality of Shopify's `@shopify/app-bridge-react`
 npm install @qumra/jisr react react-dom
 ```
 
-## Quick Start
+### Peer Dependencies
 
-### Setup the Provider
+- `react` >= 18
+- `react-dom` >= 18
 
-Wrap your application with `QumraAppBridgeProvider` at the root level:
+## Quick Start
+
+### 1. Wrap Your App with the Provider
 
-```tsx
-import React from 'react';
+```jsx
 import { QumraAppBridgeProvider } from '@qumra/jisr';
-import { App } from './App';
 
-export default function Root() {
+function App() {
   return (
-    <QumraAppBridgeProvider config={{ apiKey: 'your-app-api-key' }}>
-      <App />
+    <QumraAppBridgeProvider>
+      <YourAppComponent />
     </QumraAppBridgeProvider>
   );
 }
-```
 
-### Using Hooks in Your Components
+export default App;
+```
 
-Once the provider is set up, you can use any of the available hooks in your components:
+### 2. Use Hooks in Your Components
 
-```tsx
-import React from 'react';
-import {
-  useNavigate,
-  useToast,
-  useSaveBar,
-} from '@qumra/jisr';
+```jsx
+import { useNavigate, useToast } from '@qumra/jisr';
 
-export function ProductSettings() {
-  const navigate = useNavigate();
-  const toast = useToast();
-  const saveBar = useSaveBar();
-  const [hasChanges, setHasChanges] = React.useState(false);
-
-  const handleChange = () => {
-    setHasChanges(true);
-    saveBar.show({
-      saveLabel: 'Save Changes',
-      discardLabel: 'Discard',
-    });
-  };
+function MyComponent() {
+  const { navigate } = useNavigate();
+  const { showToast } = useToast();
 
-  const handleSave = async () => {
-    try {
-      toast.show({ message: 'Saving...' });
-      // Save your data here
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      toast.show({ message: 'Saved successfully!' });
-      saveBar.hide();
-      setHasChanges(false);
-    } catch (error) {
-      toast.show({
-        message: 'Error saving changes',
-        isError: true,
-      });
-    }
+  const handleClick = () => {
+    showToast('Hello from embedded app!', 'success');
+    navigate('/dashboard');
   };
 
-  return (
-    <div>
-      <input
-        type="text"
-        placeholder="Product name"
-        onChange={handleChange}
-      />
-      <button onClick={handleSave}>Save</button>
-      <button onClick={() => navigate('/products')}>
-        Back to Products
-      </button>
-    </div>
-  );
+  return <button onClick={handleClick}>Navigate & Toast</button>;
 }
 ```
 
-## Available Hooks
+## Hooks Reference
 
-### useAppBridge()
+### `useAppBridge`
 
-Get direct access to the AppBridge instance for advanced use cases:
+Access the core `AppBridge` instance directly for advanced use cases.
 
-```tsx
+```jsx
 import { useAppBridge } from '@qumra/jisr';
 
-export function MyComponent() {
+function AdvancedComponent() {
   const bridge = useAppBridge();
 
   const handleCustomAction = () => {
-    bridge.dispatch({
-      type: 'APP::CUSTOM_ACTION',
-      payload: { /* your data */ },
-    });
-
-    // Subscribe to events
-    const unsubscribe = bridge.subscribe('HOST::RESPONSE', (data) => {
-      console.log('Received:', data);
-    });
-
-    return () => unsubscribe();
+    bridge.dispatch({ type: 'CUSTOM_ACTION', payload: { /* ... */ } });
   };
 
-  return <button onClick={handleCustomAction}>Custom Action</button>;
+  return <button onClick={handleCustomAction}>Send Custom Action</button>;
 }
 ```
 
-### useNavigate()
+### `useNavigate`
 
-Navigate within the Qumra Admin:
+Navigate within the Qumra Admin interface.
 
-```tsx
+```jsx
 import { useNavigate } from '@qumra/jisr';
 
-export function NavigationComponent() {
-  const navigate = useNavigate();
+function NavigationComponent() {
+  const { navigate } = useNavigate();
 
   return (
-    <div>
-      <button onClick={() => navigate('/products')}>
-        View Products
-      </button>
-      <button
-        onClick={() => navigate('https://example.com', {
-          external: true,
-        })}
-      >
-        Open External Site
-      </button>
-    </div>
+    <>
+      <button onClick={() => navigate('/dashboard')}>Dashboard</button>
+      <button onClick={() => navigate('/settings')}>Settings</button>
+    </>
   );
 }
 ```
 
-### useToast()
+### `useToast`
 
-Show and hide toast notifications:
+Display toast notifications in the Qumra Admin UI.
 
-```tsx
+```jsx
 import { useToast } from '@qumra/jisr';
 
-export function ToastExample() {
-  const toast = useToast();
+function ToastComponent() {
+  const { showToast, hideToast } = useToast();
+
+  const handleSuccess = () => {
+    showToast('Operation successful!', 'success');
+  };
+
+  const handleError = () => {
+    showToast('Something went wrong.', 'error');
+  };
 
   return (
-    <div>
-      <button
-        onClick={() =>
-          toast.show({
-            message: 'Operation completed successfully!',
-            duration: 3000,
-          })
-        }
-      >
-        Show Success Toast
-      </button>
-      <button
-        onClick={() =>
-          toast.show({
-            message: 'An error occurred',
-            isError: true,
-            duration: 5000,
-          })
-        }
-      >
-        Show Error Toast
-      </button>
-      <button onClick={() => toast.hide()}>
-        Hide Toast
-      </button>
-    </div>
+    <>
+      <button onClick={handleSuccess}>Show Success</button>
+      <button onClick={handleError}>Show Error</button>
+    </>
   );
 }
 ```
 
-### useModal()
+### `useModal`
 
-Open and close modal dialogs:
+Open and manage modal dialogs.
 
-```tsx
+```jsx
 import { useModal } from '@qumra/jisr';
 
-export function ModalExample() {
-  const modal = useModal();
-
-  const handleOpenSettings = () => {
-    modal.open({
-      title: 'App Settings',
-      url: '/settings',
-      size: 'large',
-      primaryAction: {
-        content: 'Save',
-        onAction: () => {
-          console.log('Save clicked');
-          modal.close();
-        },
-      },
-      secondaryActions: [
-        {
-          content: 'Cancel',
-          onAction: () => {
-            modal.close();
-          },
-        },
-      ],
+function ModalComponent() {
+  const { openModal, closeModal } = useModal();
+
+  const handleOpenModal = () => {
+    openModal({
+      title: 'Confirm Action',
+      content: 'Are you sure you want to proceed?',
     });
   };
 
-  return <button onClick={handleOpenSettings}>Open Settings</button>;
+  return (
+    <>
+      <button onClick={handleOpenModal}>Open Modal</button>
+      <button onClick={closeModal}>Close Modal</button>
+    </>
+  );
 }
 ```
 
-### useSaveBar()
+### `useSaveBar`
 
-Show a save bar for unsaved changes:
+Show/hide the save bar for form changes.
 
-```tsx
+```jsx
 import { useSaveBar } from '@qumra/jisr';
+import { useState } from 'react';
 
-export function FormWithSaveBar() {
-  const saveBar = useSaveBar();
-  const [isDirty, setIsDirty] = React.useState(false);
+function FormComponent() {
+  const { showSaveBar, hideSaveBar } = useSaveBar();
+  const [isDirty, setIsDirty] = useState(false);
 
-  const handleChange = () => {
-    if (!isDirty) {
-      setIsDirty(true);
-      saveBar.show();
-    }
+  const handleFieldChange = (e) => {
+    setIsDirty(true);
+    showSaveBar();
   };
 
   const handleSave = async () => {
-    await saveData();
+    // Save logic
+    hideSaveBar();
     setIsDirty(false);
-    saveBar.hide();
   };
 
   return (
     <form>
-      <input onChange={handleChange} />
-      <button onClick={handleSave}>Save</button>
+      <input onChange={handleFieldChange} />
+      {isDirty && <button onClick={handleSave}>Save</button>}
     </form>
   );
 }
 ```
 
-### useTitleBar()
+### `useTitleBar`
 
-Update the title bar:
+Update the page title in the Qumra Admin.
 
-```tsx
+```jsx
 import { useTitleBar } from '@qumra/jisr';
+import { useEffect } from 'react';
 
-export function PageWithTitle() {
-  const titleBar = useTitleBar();
-
-  React.useEffect(() => {
-    titleBar.update({
-      title: 'Products',
-      subtitle: 'Manage your store products',
-      breadcrumbs: [
-        { content: 'Admin', url: '/' },
-        { content: 'Products' },
-      ],
-    });
-  }, [titleBar]);
+function PageComponent() {
+  const { updateTitleBar } = useTitleBar();
 
-  return <div>Products page content</div>;
+  useEffect(() => {
+    updateTitleBar('My Page Title');
+  }, [updateTitleBar]);
+
+  return <div>Page content</div>;
 }
 ```
 
-### useFullscreen()
+### `useFullscreen`
 
-Enter and exit fullscreen mode:
+Enter and exit fullscreen mode.
 
-```tsx
+```jsx
 import { useFullscreen } from '@qumra/jisr';
 
-export function FullscreenComponent() {
-  const fullscreen = useFullscreen();
+function FullscreenComponent() {
+  const { enterFullscreen, exitFullscreen } = useFullscreen();
 
   return (
-    <div>
-      <button onClick={() => fullscreen.enter()}>
-        Enter Fullscreen
-      </button>
-      <button onClick={() => fullscreen.exit()}>
-        Exit Fullscreen
-      </button>
-    </div>
+    <>
+      <button onClick={enterFullscreen}>Go Fullscreen</button>
+      <button onClick={exitFullscreen}>Exit Fullscreen</button>
+    </>
   );
 }
 ```
 
-### useAuthenticatedFetch()
+### `useAuthenticatedFetch`
 
-Make authenticated API requests with automatic session token injection:
+Make authenticated requests to the Qumra API with automatic auth headers.
 
-```tsx
+```jsx
 import { useAuthenticatedFetch } from '@qumra/jisr';
+import { useEffect, useState } from 'react';
+
+function DataComponent() {
+  const { fetch: authenticatedFetch } = useAuthenticatedFetch();
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    const loadData = async () => {
+      setLoading(true);
+      try {
+        const response = await authenticatedFetch('/api/data');
+        const json = await response.json();
+        setData(json);
+      } catch (error) {
+        console.error('Fetch failed:', error);
+      } finally {
+        setLoading(false);
+      }
+    };
 
-export function DataFetcher() {
-  const authenticatedFetch = useAuthenticatedFetch();
-  const [data, setData] = React.useState(null);
-
-  const loadData = async () => {
-    try {
-      const response = await authenticatedFetch('/api/products');
-      const result = await response.json();
-      setData(result);
-    } catch (error) {
-      console.error('Error fetching data:', error);
-    }
-  };
-
-  React.useEffect(() => {
     loadData();
-  }, []);
+  }, [authenticatedFetch]);
 
-  return <div>{data ? JSON.stringify(data) : 'Loading...'}</div>;
+  if (loading) return <div>Loading...</div>;
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
 }
 ```
 
-## API Reference
-
-### ActionType
-
-Constants for all available action types:
-
-```typescript
-import { ActionType } from '@qumra/jisr';
-
-const actions = {
-  NAVIGATE: ActionType.NAVIGATE,
-  TOAST_SHOW: ActionType.TOAST_SHOW,
-  TOAST_HIDE: ActionType.TOAST_HIDE,
-  MODAL_OPEN: ActionType.MODAL_OPEN,
-  MODAL_CLOSE: ActionType.MODAL_CLOSE,
-  SAVE_BAR_SHOW: ActionType.SAVE_BAR_SHOW,
-  SAVE_BAR_HIDE: ActionType.SAVE_BAR_HIDE,
-  TITLE_BAR_UPDATE: ActionType.TITLE_BAR_UPDATE,
-  LOADING_START: ActionType.LOADING_START,
-  LOADING_STOP: ActionType.LOADING_STOP,
-  FULLSCREEN_ENTER: ActionType.FULLSCREEN_ENTER,
-  FULLSCREEN_EXIT: ActionType.FULLSCREEN_EXIT,
-};
-```
-
-### Action Creator Functions
+## Action Creators
 
-Helper functions to create properly formatted actions:
+For advanced usage, dispatch actions directly via the `AppBridge`:
 
-```typescript
+```jsx
 import {
   navigate,
   showToast,
@@ -378,53 +281,84 @@ import {
   exitFullscreen,
 } from '@qumra/jisr';
 
-// Use with useAppBridge()
 const bridge = useAppBridge();
-bridge.dispatch(navigate('/products'));
-bridge.dispatch(showToast('Success!'));
+
+// Navigate
+bridge.dispatch(navigate('/path'));
+
+// Toast notifications
+bridge.dispatch(showToast('Message', 'success'));
+bridge.dispatch(hideToast());
+
+// Modals
+bridge.dispatch(openModal({ title: 'Title', content: 'Content' }));
+bridge.dispatch(closeModal());
+
+// Save bar
+bridge.dispatch(showSaveBar());
+bridge.dispatch(hideSaveBar());
+
+// Title bar
+bridge.dispatch(updateTitleBar('New Title'));
+
+// Loading state
+bridge.dispatch(startLoading());
+bridge.dispatch(stopLoading());
+
+// Fullscreen
+bridge.dispatch(enterFullscreen());
+bridge.dispatch(exitFullscreen());
 ```
 
-## Type Definitions
+## TypeScript
 
-All types are exported for TypeScript projects:
+All types are exported from the main package:
 
 ```typescript
-import type {
+import {
+  AppBridge,
   AppBridgeConfig,
   AppBridgeAction,
   AppBridgeState,
   AppContext,
-  NavigateOptions,
-  ToastOptions,
-  ModalOptions,
-  SaveBarOptions,
-  TitleBarOptions,
+  ActionType,
   UseToastResult,
   UseModalResult,
+  UseNavigateResult,
   UseSaveBarResult,
-  UseFullscreenResult,
   UseTitleBarResult,
+  UseFullscreenResult,
+  UseAuthenticatedFetchResult,
 } from '@qumra/jisr';
 ```
 
-## Error Handling
+### Example Type Usage
 
-All hooks require the `QumraAppBridgeProvider` to be set up. Using them outside the provider will throw an error:
+```typescript
+import { AppBridgeAction, ActionType } from '@qumra/jisr';
 
-```
-Error: useAppBridge must be used within a QumraAppBridgeProvider
+const myAction: AppBridgeAction = {
+  type: ActionType.NAVIGATE,
+  payload: { path: '/dashboard' },
+};
 ```
 
-Make sure your component is wrapped with the provider or is a child of a component that is wrapped.
+## Qumra Ecosystem
 
-## Best Practices
-
-1. **Always set up the provider at the root level** of your application
-2. **Use the specific hooks** instead of `useAppBridge()` for most use cases
-3. **Handle errors gracefully** when making API calls
-4. **Clean up subscriptions** if you use direct subscriptions via `useAppBridge()`
-5. **Use TypeScript** for better type safety and IDE autocomplete
+| Package | Description |
+|---------|-------------|
+| [@qumra/jisr](https://www.npmjs.com/package/@qumra/jisr) | React hooks for app bridge communication |
+| [@qumra/config](https://www.npmjs.com/package/@qumra/config) | Centralized config management for Qumra apps |
+| [@qumra/logger](https://www.npmjs.com/package/@qumra/logger) | Structured logging utility |
+| [@qumra/ui](https://www.npmjs.com/package/@qumra/ui) | Reusable React component library |
+| [@qumra/api-client](https://www.npmjs.com/package/@qumra/api-client) | API client for Qumra services |
+| [@qumra/types](https://www.npmjs.com/package/@qumra/types) | Shared TypeScript type definitions |
+| [@qumra/utils](https://www.npmjs.com/package/@qumra/utils) | Common utility functions |
 
 ## License
 
-ISC
+ISC © [Nicetag](https://github.com/nicetag)
+
+## Repository
+
+[github.com/nicetag/qumra-apps-sdk](https://github.com/nicetag/qumra-apps-sdk)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qumra/jisr",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "React hooks and utilities for communicating with the Qumra Admin from embedded apps — navigation, toasts, modals, and more",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",