JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1137
  • Score
    100M100P100Q113836F
  • License Apache-2.0

Communication bridge SDK for embedded apps in Salla Dashboard

Package Exports

  • @salla.sa/embedded-sdk

Readme

@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

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

async function bootstrap() {
  // Initialize and connect to the Salla Dashboard
  const state = await embedded.init({
    app_id: "your-app-id",
    debug: true,
  });

  console.log("Connected! Store ID:", state.storeId);
  console.log("Theme:", state.isDarkMode ? "dark" : "light");

  // Hide loading indicator
  embedded.ui.loading.hide();

  // Set up breadcrumbs
  embedded.ui.breadcrumbs.set([
    { label: "Home", path: "/" },
    { label: "My App" },
  ]);
}

bootstrap();

UMD (Browser Global)

<script src="https://unpkg.com/@salla.sa/embedded-sdk/dist/index.umd.js"></script>
<script>
  SallaEmbeddedSDK.embedded
    .init({ app_id: "your-app-id" })
    .then(function (state) {
      console.log("Connected!", state);
      SallaEmbeddedSDK.embedded.ui.loading.hide();
    });
</script>

API Overview

Initialization

const state = await embedded.init({
  app_id: "your-app-id", // Required: Your app identifier
  env: "prod", // Optional: 'prod' | 'dev'
  debug: false, // Optional: Enable debug logging
});

Returns EmbeddedState with merchant context:

interface EmbeddedState {
  ready: boolean;
  token?: string;
  storeId?: number;
  userId?: number;
  merchantPlan?: string;
  isDarkMode?: boolean;
  locale?: string;
  baseUrl?: string;
  baseApiUrl?: string;
}

Auth Module

// Get authentication data
const token = embedded.auth.getAccessToken();
const storeId = embedded.auth.getStoreId();
const userId = embedded.auth.getUserId();
const plan = embedded.auth.getMerchantPlan();
const locale = embedded.auth.getLocale();

// Check authentication status
if (embedded.auth.isAuthenticated()) {
  // Make authenticated API calls
}

// Auth actions
embedded.auth.logout(); // Logout user
embedded.auth.logout("/custom-redirect"); // With redirect
embedded.auth.refreshToken(); // Refresh token (page reload)
embedded.auth.verifyToken(); // Verify token

UI Module

// Loading
embedded.ui.loading.show(); // Show loading
embedded.ui.loading.show("component"); // Component-level loading
embedded.ui.loading.hide(); // Hide loading
embedded.ui.loading.set(false); // Direct control

// Overlay (fullscreen mode)
embedded.ui.overlay.open();
embedded.ui.overlay.close();

// Breadcrumbs
embedded.ui.breadcrumbs.set([
  { label: "Dashboard", path: "/" },
  { label: "Products", path: "/products" },
  { label: "Edit Product" },
]);
embedded.ui.breadcrumbs.clear();

// 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

// 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
// Set primary action button
embedded.nav.setAction({
  title: "Create Product",
  url: "/products/new",
});

// With dropdown actions
embedded.nav.setAction({
  title: "Actions",
  value: "main",
  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
const isDark = embedded.getState().isDarkMode;

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

Error Reporting

try {
  await riskyOperation();
} catch (err) {
  embedded.reportError(err, { operation: "riskyOperation" });
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  EmbeddedState,
  InitOptions,
  BreadcrumbItem,
  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