@sovereign-workspace/sdk-iframe

The iframe-side SDK for building external apps for Sovereign Workspace. Your app runs in a sandboxed <iframe> inside the workspace and talks to the host over a validated postMessage bridge — with the same API shape a built-in app would use.

Full guide: https://sovereignworkspace.org/developers

Install

npm install @sovereign-workspace/sdk-iframe

Quick start

import { createWorkspaceSdk } from '@sovereign-workspace/sdk-iframe';

const sdk = createWorkspaceSdk();

// A short-lived, scoped token the host minted for your app at launch (or null).
const token = await sdk.ext.getToken();

// Show a workspace notification.
await sdk.notifications.show({ title: 'Hello', body: 'from my app', variant: 'info' });

// Send an IPC message to another app (delivered only if both manifests consent).
await sdk.ipc.send('chat', { type: 'greeting', text: 'hi' });

// Receive IPC messages addressed to your app.
const off = sdk.ipc.on('my-app', (env) => {
  console.log('message from', env.sender, env.data);
});

// Runtime info.
const mode = await sdk.system.getRuntimeMode(); // 'standalone' when run outside the workspace

Runs standalone too

When your app is opened outside the workspace (direct URL, local npm run dev), there is no host to talk to. createWorkspaceSdk() detects this and returns a no-op client: every call resolves to a safe default, so you can build and test the whole UI without the workspace running. The real bridge is wired only when your app is embedded.

To lock the bridge to a specific host origin, pass it in:

const sdk = createWorkspaceSdk('https://workspace.example.org');

API

| Module | Method | Notes | |---|---|---| | ipc | send(recipient, data) | Delivered only on mutual manifest consent (you list them, they accept you). | | ipc | on(recipient, handler) → unsubscribe | Subscribe to messages addressed to your app. | | notifications | show(payload) | Show a workspace notification. | | system | getRuntimeContext() | Signed-in username and runtime details. | | system | getRuntimeMode() | 'standalone' outside the workspace. | | system | isNativeShell() | true in the native (Tauri) shell. | | ext | getToken() | The scoped app token minted at launch, or null. | | — | dispose() | Tear down the bridge subscription. |

The host stamps your app's identity on every call — a message payload cannot spoof its appId. Capability and consent checks are enforced host-side, so the bridge never widens what your app is allowed to do.

Building from source

npm run build   # tsc → dist/ (ESM + .d.ts)

Pure ES module, no runtime dependencies.

License

Apache-2.0