// packages/embedded-sdk/README.md

@classspace/embedded-sdk

Lightweight browser SDK for embedding external apps inside ClassSpace. Handles the host postMessage bridge, launch token refresh, and optional Yjs realtime connectivity for app-specific shards (e.g., apps:timer).

Usage

import { createEmbeddedSdk } from '@classspace/embedded-sdk';

const sdk = createEmbeddedSdk();

sdk.lifecycle.onInit((payload) => {
  console.log('activity init', payload);
});

sdk.tokens.onUpdate((auth) => {
  console.log('launch token exp', auth?.exp);
});

const { doc, awareness, disconnect } = await sdk.yjs.connect({ docKey: 'apps:timer' });

Features

• Origin-gated postMessage bridge (host:init, host:auth, host:visibility, etc.).
• Token helper with automatic app:token:request retries.
• sdk.yjs.connect({ docKey }) to join ClassSpace Durable Object shards with scope-checked launch tokens.
• Awareness helpers with throttled broadcasts (≤10 Hz).
• Abortable connection via AbortController.

See docs/embedded-apps/CONTRACT.md for the full lifecycle contract.