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-sdkQuick Start
ES Modules (Recommended)
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 tokenUI 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 heightNav Module
// 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