App Bridge (@qumra/jisr)

The App Bridge is the communication layer between your embedded app and the Qumra Admin panel. It provides React hooks for navigation, toasts, modals, save bars, and more.

Installation

npm

npm install @qumra/jisr

pnpm

pnpm install @qumra/jisr

Yarn

yarn add @qumra/jisr

Setup

Wrap your app with QumraAppBridgeProvider to enable all App Bridge hooks:

app/root.tsx

import { QumraAppBridgeProvider } from "@qumra/jisr";

export default function App() {
  return (
    <QumraAppBridgeProvider config={{ apiKey: "your-app-api-key" }}>
      <Outlet />
    </QumraAppBridgeProvider>
  );
}

Configuration

Property	Type	Default	Description
apiKey	string	--	Your app's API key (client_id).
host	string	https://app.qumra.cloud	The Qumra Admin panel URL.

Core Concepts

The App Bridge uses postMessage to communicate between the iframe (your app) and the parent window (Qumra Admin). It manages:

• State -- Loading state and app context (store, locale, currency, timezone).
• Actions -- Dispatched from your app to the admin panel (navigate, show toast, etc.).
• Events -- Subscribed from the admin panel to your app.

AppContext

After initialization, the bridge provides context about the current store:

interface AppContext {
  store: string;          // Store domain
  locale: string;         // Current locale (e.g. "ar", "en")
  currency: string;       // Store currency code
  timezone: string;       // Store timezone
  sessionToken?: string;  // Session token for API calls
}

Available Hooks

Hook	Purpose
useAppBridge()	Access the AppBridge instance directly
useNavigate()	Navigate within the Qumra Admin
useToast()	Show toast notifications
useModal()	Open/close modals
useSaveBar()	Show save/discard bar
useFullscreen()	Enter/exit fullscreen mode
useTitleBar()	Update the page title bar
useNavigationMenu()	Update navigation menu items
useAuthenticatedFetch()	Make authenticated API calls

useAppBridge()

Access the underlying AppBridge instance for advanced use cases:

import { useAppBridge } from "@qumra/jisr";

function MyComponent() {
  const appBridge = useAppBridge();

  // Access the current state
  const state = appBridge.getState();
  console.log(state.context.store);  // "mystore.qumra.store"
  console.log(state.loading);        // false

  // Dispatch a custom action
  appBridge.dispatch(someAction);

  // Subscribe to events
  appBridge.subscribe("someEvent", (data) => {
    console.log(data);
  });
}

useAuthenticatedFetch()

Make authenticated API calls from the client side:

import { useAuthenticatedFetch } from "@qumra/jisr";

function MyComponent() {
  const fetch = useAuthenticatedFetch();

  async function loadProducts() {
    const response = await fetch("/api/products");
    const data = await response.json();
    return data;
  }
}

Action Creators

For advanced use cases, you can import action creators directly:

import {
  navigate,
  showToast,
  hideToast,
  openModal,
  closeModal,
  showSaveBar,
  hideSaveBar,
  updateTitleBar,
  startLoading,
  stopLoading,
  enterFullscreen,
  exitFullscreen,
} from "@qumra/jisr";

// Dispatch actions manually
appBridge.dispatch(showToast({ message: "Saved!" }));
appBridge.dispatch(navigate("/products"));

Next Steps

• Navigation -- Navigate within the admin and configure navigation menus.
• Toast & Modal -- Display notifications and dialogs.
• Save Bar -- Show save/discard bars for form changes.
• Title Bar & Fullscreen -- Control the title bar and fullscreen mode.