@salla.sa/embedded-sdk

@salla.sa/embedded-sdk

Communication bridge SDK for third-party apps embedded in the Salla Merchant Dashboard.

Installation

npm install @salla.sa/embedded-sdk
# or
pnpm add @salla.sa/embedded-sdk
# or
yarn add @salla.sa/embedded-sdk

Quick Start

ES Modules (Recommended)

import { embedded } from "@salla.sa/embedded-sdk";

async function bootstrap() {
  try {
    // 1. Initialize SDK and get layout info
    const { layout } = await embedded.init({ debug: true });
    console.log("Theme:", layout.theme);
    console.log("Locale:", layout.locale);

    // 2. Get token from URL and verify with your backend
    const token = embedded.auth.getToken();
    if (!token) {
      throw new Error("No token found");
    }

    const verified = await verifyWithBackend(token);
    if (!verified) {
      throw new Error("Token verification failed");
    }

    // 3. Signal that app is ready (removes host loading overlay)
    embedded.ready();

    // 4. Set up your app
    embedded.page.setTitle("My App");
  } catch (err) {
    // Exit embedded view (navigates to apps page)
    embedded.destroy();
  }
}

bootstrap();

UMD (Browser Global)

<script src="https://unpkg.com/@salla.sa/embedded-sdk/dist/index.umd.js"></script>
<script>
  const embedded = SallaEmbeddedSDK.embedded;

  embedded.init({ debug: true }).then(function (result) {
    console.log("Layout:", result.layout);

    const token = embedded.auth.getToken();
    // ... verify token and call embedded.ready()
  });
</script>

Script Access via Salla Object

The SDK is also accessible via the global Salla object:

<script>
  // Access SDK from Salla namespace
  Salla.embedded.init({ debug: true });
</script>

API Overview

Initialization

const { layout } = await embedded.init({
  debug: false, // Optional: Enable debug logging
});

Returns layout information from the host:

interface LayoutInfo {
  theme: "light" | "dark";
  width: number;
  locale: string;
  currency: string;
}

Core Methods

// Signal app is ready (removes host loading overlay)
embedded.ready();

// Get current state
const state = embedded.getState();

// Check if initialized
const ready = embedded.isReady();

// Subscribe to initialization
embedded.onInit((state) => {
  console.log("Initialized with layout:", state.layout);
});

// Send log message to host
embedded.log("error", "Something failed", { context: "data" });

Auth Module

// Get token from URL (?token=XXX)
const token = embedded.auth.getToken();

// Request token refresh (re-renders iframe with new token)
embedded.auth.refresh();

Destroy

// Exit embedded view and navigate back to app page
embedded.destroy();

UI Module

// Loading (in-app loading states)
embedded.ui.loading.show(); // Show loading
embedded.ui.loading.show("component"); // Component-level
embedded.ui.loading.hide(); // Hide loading

// Toast Notifications
embedded.ui.toast.success("Product saved!");
embedded.ui.toast.error("Something went wrong");
embedded.ui.toast.warning("Please review input");
embedded.ui.toast.info("New features available");
embedded.ui.toast.success("Saved!", 5000); // Custom duration

// Generic toast
embedded.ui.toast.show({
  type: "success",
  message: "Done!",
  duration: 3000,
});

// Modal
embedded.ui.modal.open("my-modal", { data: 123 });
embedded.ui.modal.close("my-modal");

// Confirm Dialog (async)
const result = await embedded.ui.confirm({
  title: "Delete Product?",
  message: "This action cannot be undone.",
  confirmText: "Delete",
  cancelText: "Cancel",
  variant: "danger", // 'danger' | 'warning' | 'info'
});

if (result.confirmed) {
  await deleteProduct();
}

Page Module

// Set page title in host
embedded.page.setTitle("Product Details");

// SPA Navigation (React Router)
embedded.page.navigate("/products");
embedded.page.navigate("/orders", { replace: true });
embedded.page.navigate("/item", { state: { id: 123 } });

// Full Page Redirect
embedded.page.redirect("https://external-site.com");

// Auto-detect (internal → navigate, external → redirect)
embedded.page.navTo("/products");
embedded.page.navTo("https://external.com");

// Iframe Resize
embedded.page.resize(800);
embedded.page.autoResize(); // Auto-detect content height

Nav Module

// Set primary action button with onClick
embedded.nav.setAction({
  title: "Create Product",
  onClick: () => {
    // Handle click
    console.log("Create product clicked");
  },
});

// With optional props
embedded.nav.setAction({
  title: "Save",
  subTitle: "Save changes",
  icon: "sicon-save",
  disabled: false,
  onClick: () => {
    handleSave();
  },
});

// With dropdown actions
embedded.nav.setAction({
  title: "Actions",
  value: "main",
  onClick: () => {
    // Handle main action click
  },
  extendedActions: [
    { title: "Import", url: "/import" },
    { title: "Export", value: "export" },
  ],
});

// Listen for action clicks
const unsubscribe = embedded.nav.onActionClick((url, value) => {
  if (value === "export") {
    handleExport();
  }
});

// Clear action button
embedded.nav.clearAction();

Checkout Module

embedded.checkout.create({
  items: [{ productId: 123, quantity: 1 }],
  amount: 99.99,
  currency: "SAR",
});

Theme Support

// Get current theme from state
const theme = embedded.getState().layout.theme;

// Listen for theme changes
const unsubscribe = embedded.onThemeChange((theme) => {
  document.body.classList.toggle("dark", theme === "dark");
});

TypeScript Support

Full TypeScript support with exported types:

import type {
  EmbeddedState,
  LayoutInfo,
  InitOptions,
  ToastOptions,
  ToastType,
  ConfirmOptions,
  ConfirmResult,
  PrimaryActionConfig,
  ExtendedAction,
  CheckoutPayload,
} from "@salla.sa/embedded-sdk";

Build Formats

Format	File	Usage
ESM	dist/index.es.js	Modern bundlers (Vite, etc.)
CommonJS	dist/index.cjs.js	Node.js
UMD	dist/index.umd.js	Browser global
SystemJS	dist/index.system.js	SystemJS/microfrontends

Development

pnpm install    # Install dependencies
pnpm dev        # Development build with watch
pnpm build      # Production build
pnpm lint       # Lint code
pnpm typecheck  # Type check