284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
66 lines
2.5 KiB
Markdown
66 lines
2.5 KiB
Markdown
# Client UI SDK Guide (Iframe)
|
||
|
||
This guide explains how iframe apps interact with the host via the Extension Iframe SDK and how to build consistent UIs with the UI kit.
|
||
|
||
## Packages
|
||
- `@alga/extension-iframe-sdk` — handshake, auth, navigation, theme, telemetry
|
||
- `@alga/ui-kit` — accessible components, design tokens, hooks
|
||
|
||
## Getting Started
|
||
|
||
```tsx
|
||
import { BridgeProvider, useExtension } from '@alga/extension-iframe-sdk';
|
||
import { Button, DataTable } from '@alga/ui-kit';
|
||
|
||
function App() {
|
||
const { context } = useExtension(); // { extensionId, authHeaders, gatewayBase, theme }
|
||
|
||
async function sync() {
|
||
await fetch(`${context.gatewayBase}/api/ext/${context.extensionId}/agreements/sync`, {
|
||
method: 'POST',
|
||
headers: { ...context.authHeaders, 'content-type': 'application/json' },
|
||
body: JSON.stringify({ force: true })
|
||
});
|
||
}
|
||
|
||
return <Button onClick={sync}>Sync</Button>;
|
||
}
|
||
|
||
export default function Root() {
|
||
return (
|
||
<BridgeProvider>
|
||
<App />
|
||
</BridgeProvider>
|
||
);
|
||
}
|
||
```
|
||
|
||
## Auth & Requests
|
||
|
||
- Use `context.authHeaders` for gateway calls; do not forward end‑user tokens
|
||
- Always call `/api/ext/${extensionId}/...` paths (the Gateway proxies to Runner `POST /v1/execute`)
|
||
- Gateway reference: [server/src/app/api/ext/[extensionId]/[[...path]]/route.ts](../../../server/src/app/api/ext/%5BextensionId%5D/%5B%5B...path%5D%5D/route.ts)
|
||
|
||
## Navigation
|
||
|
||
- Prefer host‑managed navigation events when integrated in larger flows
|
||
- SDK exposes helpers to request navigation changes from the host (implementation detail subject to SDK version)
|
||
|
||
## Theme
|
||
|
||
- UI kit consumes CSS variables provided by the host
|
||
- The bridge emits theme updates; subscribe if your app needs to react dynamically
|
||
|
||
## Telemetry & Logging
|
||
|
||
- Use SDK/Host APIs to emit telemetry and structured logs rather than `console.*` for operational visibility
|
||
|
||
## Security Notes
|
||
|
||
- Do not evaluate code at runtime (no template engines)
|
||
- Avoid cross‑origin requests; route everything via the gateway
|
||
- UI assets are served by the Runner at `${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]`; the Next.js ext-ui route gates/redirects when rust-host mode is enabled.
|
||
- Iframe src is constructed by [buildExtUiSrc()](../../../server/src/lib/extensions/ui/iframeBridge.ts:38) and bootstrapped via [bootstrapIframe()](../../../server/src/lib/extensions/ui/iframeBridge.ts:45)
|
||
|
||
See also: [DataTable Integration Guide](datatable-integration-guide.md), [Manifest v2](manifest_schema.md), and [API Routing Guide](api-routing-guide.md).
|