App Bridge (embedded UI)

https://your-app.com/embed
  ?shop=<store-id>
  &name=<store-name>
  &user=<salesive-user-id>
  &embedded=1
  &host=https://app.salesive.com

import { onAppWake } from "salesive-dev-tools/permissions";

onAppWake(() => {
  connectWebSocket();
  startOrderPolling();
  prefetchCriticalData();
});

dashboard opens
      │
      ▼
 salesive:app-wake          ← iframe loaded in background; start sync, sockets, etc.
      │
      │  (merchant taps dock icon)
      ▼
 salesive:app-opened        ← app is now visible; show fresh UI, stop any "background only" modes
      │
      │  (merchant presses − or swipes down)
      ▼
 salesive:app-minimized     ← app hidden but still running; pause heavy rendering work
      │
      │  (merchant reopens)
      ▼
 salesive:app-opened        ← visible again
      │
      │  (merchant presses × / close)
      ▼
 salesive:app-closed        ← dashboard has told the app it was dismissed; save unsaved state
                               (app is still running in background — wake/open may follow)

 salesive:store-changed     ← merchant switched to another of their stores.
                               Your iframe RELOADS right after, with the new `shop` param.

 salesive:app-logout        ← merchant logged out. Clear your own session now;
                               your iframe is destroyed moments later.

import { pickFiles } from "salesive-dev-tools/permissions";

// Single image (the common case):
const [logo] = await pickFiles();
if (logo) setLogoUrl(logo.url);

// Up to 5 images or videos:
const files = await pickFiles({ mediaType: "all", multiple: true, maxSelection: 5 });

npm install salesive-dev-tools

import {
  PERMISSIONS,
  DURATIONS,
  APP_EVENTS,
  requestPermission,
  getGrantedPermissions,
  pickFiles,
  onLaunch,
  onAppWake,
  onAppOpened,
  onAppMinimized,
  onAppClosed,
  onLogout,
  onStoreChanged,
  onEvent,
} from "salesive-dev-tools/permissions";

import { requestPermission, onAppWake } from "salesive-dev-tools";

function onAppWake(callback: () => void): () => void  // returns unsubscribe

import { onAppWake } from "salesive-dev-tools/permissions";

onAppWake(async () => {
  await connectWebSocket();
  const grants = await getGrantedPermissions();
  if (PERMISSIONS.AUTO_LAUNCH in grants) scheduleAutoLaunchTimer();
});

function onAppOpened(callback: () => void): () => void

onAppOpened(() => {
  refreshDashboard();
  clearBadge();
});

function onAppMinimized(callback: () => void): () => void

onAppMinimized(() => {
  pauseHeavyAnimations();
  reducePollingFrequency();
});

function onAppClosed(callback: () => void): () => void

onAppClosed(() => {
  saveDraft();
  cancelPendingAnimations();
});

function onLogout(callback: () => void): () => void  // returns unsubscribe

import { onLogout } from "salesive-dev-tools/permissions";

onLogout(() => {
  localStorage.removeItem("my-app-token");
  sessionStorage.clear();
});

function onStoreChanged(
  callback: (store: {
    shopId         : string;         // now-active store; matches the new `shop` param
    shopName?      : string;         // display name, when the dashboard knows it
    previousShopId : string | null;  // the store just left, or null on a cold switch
  }) => void
): () => void

import { onStoreChanged } from "salesive-dev-tools/permissions";

onStoreChanged(({ shopId, previousShopId }) => {
  if (previousShopId) caches.delete(`orders-${previousShopId}`);
  console.log("now operating on store", shopId);
});

function requestPermission(
  permission : Permission,
  options?   : DurationOption[],  // duration choices; omit = all five. First = default.
  timeoutMs? : number,            // default 30 000 ms
): Promise<boolean>

import { PERMISSIONS, DURATIONS, requestPermission } from "salesive-dev-tools/permissions";

// Check existing grant first — no modal shown for this call:
const grants = await getGrantedPermissions();

if (!(PERMISSIONS.AUTO_LAUNCH in grants)) {
  // Request — show 7-day and 31-day options:
  const granted = await requestPermission(
    PERMISSIONS.AUTO_LAUNCH,
    [DURATIONS.SEVEN_DAYS, DURATIONS.THIRTY_ONE_DAYS]
  );
  if (!granted) return; // merchant denied
}

function getGrantedPermissions(timeoutMs?: number): Promise<PermissionGrantMap>

interface GrantRecord {
  mode      : "once" | "1day" | "7days" | "14days" | "31days";
  grantedAt : string;           // ISO-8601 timestamp
  expiresAt : string | null;    // null for "once" grants
  usedAt    : string | null;    // set after a "once" grant is consumed
}

onAppWake(async () => {
  const grants = await getGrantedPermissions();

  if (PERMISSIONS.AUTO_LAUNCH in grants) {
    // Merchant already approved — set up the timer directly
    startAutoLaunchTimer(grants[PERMISSIONS.AUTO_LAUNCH].expiresAt);
  }
});

// Auto-reopen after 30 s when minimized and AUTO_LAUNCH is granted:
onAppMinimized(() => {
  const timer = setTimeout(onLaunch, 30_000);
  const unsub = onAppOpened(() => { clearTimeout(timer); unsub(); });
});

function pickFiles(options?: PickFilesOptions): Promise<PickedFile[]>

interface PickFilesOptions {
  mediaType?    : "images" | "videos" | "all";  // default "images"
  multiple?     : boolean;                       // default false
  maxSelection? : number;                        // cap when multiple is on
  timeoutMs?    : number;                         // default 600 000 (10 min)
}

interface PickedFile {
  id       : string;
  name     : string;
  url      : string;     // public URL — use directly as a src, or store it
  mimetype : string;     // e.g. "image/png"
  size?    : string;     // human-readable, e.g. "1.2 MB"
  isVideo  : boolean;
}

import { pickFiles } from "salesive-dev-tools/permissions";

async function chooseBanner() {
  const [file] = await pickFiles({ mediaType: "images" });
  if (!file) return;                 // merchant cancelled — empty array
  await saveBannerUrl(file.url);
}

// Multiple selection:
const files = await pickFiles({ mediaType: "all", multiple: true, maxSelection: 5 });
files.forEach((f) => console.log(f.name, f.url));

function onEvent(
  type     : string,
  callback : (data: Record<string, unknown>) => void,
): () => void

import { APP_EVENTS, onEvent } from "salesive-dev-tools/permissions";

// Forward all lifecycle events to your analytics:
for (const type of Object.values(APP_EVENTS)) {
  onEvent(type, (data) => analytics.track(data.type, data));
}

import { useEffect, useState } from "react";
import {
  PERMISSIONS, DURATIONS, APP_EVENTS,
  requestPermission, getGrantedPermissions,
  onLaunch, onAppWake, onAppOpened, onAppMinimized, onAppClosed,
  onLogout, onStoreChanged,
} from "salesive-dev-tools/permissions";

export default function App() {
  const [autoLaunchGranted, setAutoLaunchGranted] = useState(false);

  // Background init — fires before merchant opens the app
  useEffect(() => {
    return onAppWake(async () => {
      // Start background work immediately
      connectWebSocket();

      // Check existing grants silently
      const grants = await getGrantedPermissions();
      setAutoLaunchGranted(PERMISSIONS.AUTO_LAUNCH in grants);
    });
  }, []);

  // Foreground lifecycle
  useEffect(() => {
    const unOpen = onAppOpened(() => refreshDashboard());
    const unMin  = onAppMinimized(() => pauseHeavyWork());
    const unCls  = onAppClosed(() => saveDraft());
    return () => { unOpen(); unMin(); unCls(); };
  }, []);

  // Session boundaries — both handlers must be synchronous: the iframe is torn
  // down moments after either event fires.
  useEffect(() => {
    const unOut = onLogout(() => {
      localStorage.removeItem("my-app-token");
      sessionStorage.clear();
    });
    const unShop = onStoreChanged(({ shopId, previousShopId }) => {
      // The iframe reloads with the new ?shop= right after this, so only clear
      // what would otherwise SURVIVE that reload.
      if (previousShopId) localStorage.removeItem(`cache-${previousShopId}`);
      console.log("switching to store", shopId);
    });
    return () => { unOut(); unShop(); };
  }, []);

  // Auto-reopen when minimized (only if granted)
  useEffect(() => {
    if (!autoLaunchGranted) return;
    return onAppMinimized(() => {
      const t = setTimeout(onLaunch, 30_000);
      const u = onAppOpened(() => { clearTimeout(t); u(); });
    });
  }, [autoLaunchGranted]);

  async function handleRequestAutoLaunch() {
    const ok = await requestPermission(
      PERMISSIONS.AUTO_LAUNCH,
      [DURATIONS.SEVEN_DAYS, DURATIONS.THIRTY_ONE_DAYS]
    );
    setAutoLaunchGranted(ok);
  }

  return (
    <div>
      {autoLaunchGranted
        ? <p>✓ Auto-launch active — app will reopen when minimized.</p>
        : <button onClick={handleRequestAutoLaunch}>Enable auto-reopen</button>
      }
    </div>
  );
}