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,
  getSessionToken,
  // Dashboard UI extensions (see /apps/ui-extensions)
  isExtension,
  getExtensionContext,
  onExtensionContext,
  resizeExtension,
  autoResizeExtension,
  closeExtension,
} 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);
});

interface WriteDnsScope {
  domainId     : string;    // required; the one domain the grant covers
  domainName?  : string;    // shown to the merchant in the modal
  recordTypes? : string[];  // e.g. ["TXT", "MX"]; omit for every allowed type
}

interface RequestPermissionOptions {
  options? : DurationOption[];
  scope?   : WriteDnsScope;  // WRITE_DNS only
  reason?  : string;         // shown to the merchant; max 200 characters
}

function requestPermission(
  permission : Permission,
  options?   : DurationOption[] | RequestPermissionOptions,
  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
}

// WRITE_DNS is scoped to one domain. The merchant sees the domain, the record
// types and the reason before approving:
const granted = await requestPermission(PERMISSIONS.WRITE_DNS, {
  options: [DURATIONS.ONE_DAY, DURATIONS.SEVEN_DAYS],
  scope: {
    domainId: "66b1f0a3c2d4e5f6a7b8c9d0",
    domainName: "acme.com",
    recordTypes: ["TXT", "MX"],
  },
  reason: "Add the email verification records for this domain",
});

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 getSessionToken(options?: {
  timeoutMs?: number;     // default 10000
  forceRefresh?: boolean; // skip the local cache
}): Promise<string>

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

const token = await getSessionToken();
const res = await fetch("/api/orders", {
  headers: { Authorization: `Bearer ${token}` },
});

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>
  );
}

import { useEffect, useState } from "react";
import { isExtension, onExtensionContext, autoResizeExtension } from "salesive-dev-tools/permissions";

export default function Root() {
  return isExtension() ? <OrderBlock /> : <App />;
}

function OrderBlock() {
  const [ctx, setCtx] = useState(null);
  useEffect(() => onExtensionContext(setCtx), []);
  useEffect(() => autoResizeExtension(), []);
  if (!ctx) return null;
  return <TrackingStatus orderId={ctx.resource.id} />;
}