@zudello/embed-sdk

SDK for building embedded Zudello applications with standardized parent-iframe communication.

Installation

npm install @zudello/embed-sdk

Overview

The SDK provides entry points for different environments:

| Import Path | Consumer | Purpose | |---|---|---| | @zudello/embed-sdk | Embedded app (frontend) | Client SDK — auth, state, execute, React hooks | | @zudello/embed-sdk/host | Host app (frontend) | Parent-side iframe controller | | @zudello/embed-sdk/server | Embedded app (backend) | Token validation, Express middleware |

Quick Start

See Getting Started Guide for full examples including React integration, standalone mode, and host app setup.

Client (Embedded App)

import { ZudelloSDK } from '@zudello/embed-sdk';

const zudello = ZudelloSDK.init({
  allowedOrigins: ['https://your-parent-app.com'],
});

const auth = await zudello.get('auth');
zudello.listen('settings', (settings) => console.log(settings));
await zudello.execute('notify', { message: 'Done!', type: 'success' });

Host (Parent App)

import { ZudelloHost, loadManifest } from '@zudello/embed-sdk/host';

const manifest = await loadManifest('http://localhost:3000/manifest.json');
const host = new ZudelloHost(iframeElement, manifest, {
  allowedOrigins: ['http://localhost:3000'],
  getTransferCode: async () => {
    const res = await fetch('/api/transfer-code');
    return res.json();
  },
});

host.navigate('chat');
host.updateSettings({ agent: 'zudello' });

Zudello API Access

The SDK includes the full Zudello API client via the .api property:

const zudello = ZudelloSDK.init();
const auth = await zudello.get('auth');

const results = await zudello.api.search.query({
  model: 'invoice',
  filter: { status: 'approved' },
  limit: 50,
});

API modules: search, models, resources, config, sentences, automation, approvals, users, org, datasets, exports, quickActions, inboxes.

Documentation

• Getting Started - Quick start guide
• Client SDK Reference - Full ZudelloSDK API
• Host SDK Reference - Full ZudelloHost API and multi-instance registry
• Server SDK Reference - Backend token validation and middleware
• Manifest Schema - App manifest configuration
• Message Protocol - Low-level postMessage protocol
• Authentication - Auth flow and token refresh
• Standalone Mode - Local development without iframe
• Migration Guide - Migrating from custom postMessage

Security

Both client and host SDKs support allowedOrigins for postMessage origin validation. Always set allowedOrigins in production.

License

MIT