@axsdk/embed

iframe-based embed widget that renders the AXUI chat component from @axsdk/react inside a sandboxed iframe. Communication between the parent page and the iframe happens via postMessage.

Overview

Host Page                        iframe (srcdoc)
─────────────────────────────    ─────────────────────────────────────────
<script src="axsdk-embed.iife.js">
AXSDKEmbed.init(config)  ──────► AXSDK_INIT postMessage
                                  AXSDK.init({ ...config, axHandler: rpc })
                                  <AXUI /> mounted in document.body

AXSDK_HANDLER_REQUEST  ◄──────── axHandler(command, args)  (RPC outbound)
user axHandler callback
AXSDK_HANDLER_RESPONSE ────────► Promise resolves / rejects

Build output (dist/)

| File | Description | |---|---| | axsdk-embed.iife.js | Lightweight parent-page loader. No React. ~few KB. | | axsdk-embed-frame.iife.js | Self-contained iframe bundle (React + AXUI + CSS injected). |

Usage

1. Serve the dist files

Copy dist/axsdk-embed.iife.js and dist/axsdk-embed-frame.iife.js to a static hosting location (e.g., a CDN or your web server).

2. Add to your HTML page

<script src="https://cdn.example.com/axsdk-embed.iife.js"></script>
<script>
  AXSDKEmbed.init({
    apiKey: 'YOUR_API_KEY',
    appId:  'YOUR_APP_ID',
    // Optional: handle AI tool calls from the iframe
    axHandler: async (command, args) => {
      if (command === 'getUser') {
        return { name: 'Alice', role: 'admin' };
      }
      throw new Error(`Unknown command: ${command}`);
    },
  });
</script>

The widget iframe will appear fixed to the bottom-right corner of the viewport (420 × 680 px).

3. Custom iframe sizing (optional)

The iframe styles are injected inline via JavaScript. You can override them after calling init() by selecting the iframe with CSS:

/* Not directly possible since styles are inline — override via JS if needed */

postMessage Protocol

Parent → iframe

// Sent automatically by AXSDKEmbed.init()
{
  type: 'AXSDK_INIT',
  config: {
    apiKey: string;
    appId: string;
    // ...other serialisable config keys (axHandler is NOT forwarded)
  }
}

iframe → Parent (axHandler RPC request)

{
  type: 'AXSDK_HANDLER_REQUEST',
  requestId: string;   // unique ID for matching the response
  command: string;     // handler command name
  args: unknown;       // command arguments
}

Parent → iframe (axHandler RPC response)

{
  type: 'AXSDK_HANDLER_RESPONSE',
  requestId: string;   // matches the request
  result?: unknown;    // success value
  error?: string;      // error message (if the handler threw)
}

Development

Install dependencies

bun install

Build

# Build both bundles sequentially
bun run build

# Build only the parent loader
bun run build:embed

# Build only the iframe bundle
bun run build:frame

Package structure

packages/axsdk-embed/
├── src/
│   ├── embed.ts        # Parent-page loader (produces axsdk-embed.iife.js)
│   └── frame.tsx       # iframe React app (produces axsdk-embed-frame.iife.js)
├── vite.config.embed.ts
├── vite.config.frame.ts
├── tsconfig.json
└── package.json