Platform

The connected platform client an app receives from connect. It hides the postMessage plumbing behind a promise/callback API: intents, events, surfaces, notifications, flags, modals, navigation, routing, and telemetry. Everything authorization-shaped here is advisory — the app’s backend remains the sole gate.

Properties

appId

readonly appId: string;

This app’s id, as registered with the shell.

channelId

readonly channelId: string;

The shell-minted channel id for this connection.

config

readonly config: Record<string, unknown>;

Shell-supplied configuration for this app (e.g. feature profile, environment hints).

flags

readonly flags: {
  get: Promise<T>;
  getAll: Promise<Record<string, boolean>>;
};

App-scoped feature flags, evaluated by the shell (advisory; an unknown key defaults off).

get()

get<T>(key): Promise<T>;

Read one flag’s value.

Type Parameters

T

T = unknown

Parameters

key

string

Returns

Promise<T>

getAll()

getAll(): Promise<Record<string, boolean>>;

Read all boolean flags.

Returns

Promise<Record<string, boolean>>

initialRoute

readonly initialRoute: string;

The in-app subpath the shell asked the app to open on first render.

readonly modal: {
  open: Promise<T | null>;
};

Shell-brokered modals whose body is one of this app’s own surfaces.

open()

open<T>(opts): Promise<T | null>;

Open the modal; resolves with the body’s result, or null if dismissed.

Type Parameters

T

T = unknown

Parameters

opts

ModalOpenOptions

Returns

Promise<T | null>

notify

readonly notify: {
  toast: Promise<void>;
};

Shell-owned notifications.

toast()

toast(opts): Promise<void>;

Show a toast.

Parameters

opts

ToastOptions

Returns

Promise<void>

route

readonly route: {
  onShellNavigate: () => void;
  report: void;
};

Reconcile the app’s in-app routing with the shell.

onShellNavigate()

onShellNavigate(handler): () => void;

React to a shell-initiated navigation within this app (no reload); returns an unsubscribe function.

Parameters

handler

ShellNavigateHandler

Returns

() => void

report()

report(subpath, opts?): void;

Tell the shell the app’s internal route changed (updates the address bar). Default (false) pushes a back-able history entry; { replace: true } replaces it (filters, tabs that should not pollute the back stack). The shell ignores the echo of a navigation it just initiated.

Parameters

subpath

string

opts?

replace?

boolean

Returns

void

session

readonly session: Session;

The user snapshot at connect time. Follow later changes via the session.changed event.

state

readonly state: StateClient;

App-scoped shared state across this app’s frames (e.g. reflect a modal body’s live draft behind it). See StateClient.

telemetry

readonly telemetry: {
  error: void;
  event: void;
  timing: void;
};

Structured telemetry, correlated to the active trace.

error()

error(name, data?): void;

Record a named error.

Parameters

name

string

data?

unknown

Returns

void

event()

event(name, data?): void;

Record a named event.

Parameters

name

string

data?

unknown

Returns

void

timing()

timing(name, data?): void;

Record a named timing measurement.

Parameters

name

string

data?

unknown

Returns

void

theme

readonly theme: ThemeInfo;

The active theme. See ThemeInfo.

Methods

disconnect()

disconnect(): void;

Detach all listeners and timers for this connection.

Returns

void

embedSurface()

embedSurface(opts): SurfaceHandle;

Embed another app’s live rendered surface inline in this app’s UI. The shell brokers a nested provider iframe into opts.mount. Returns a SurfaceHandle to re-parameterise, size, or close it.

Parameters

opts

EmbedSurfaceOptions

Returns

SurfaceHandle

getRoles()

getRoles(): string[];

The user’s flat roles from the session, for AFFORDANCES — show/hide a control, decide whether to offer an embed. ADVISORY ONLY: a tampered value just changes what the client shows or attempts; the app’s backend independently introspects the live session and is the sole gate. Synchronous — a snapshot delivered in the handshake (refreshed on reconnect), not a round trip.

Returns

string[]

hasRole()

hasRole(role): boolean;

Whether the advisory roles include role; for affordances only, never enforcement.

Parameters

role

string

Returns

boolean

invoke()

invoke<T>(
   intent,
   payload,
options?): Promise<T>;

Call an intent provided by some other app, brokered by the shell; rejects with a PlatformError on failure.

Type Parameters

T

T = unknown

Parameters

intent

string

payload

unknown

options?

InvokeOptions

Returns

Promise<T>

log()

log(
   level,
   message,
   fields?): void;

Emit a structured, trace-correlated log line (stamped with the app id, trace id, and timestamp, collected in the shell-side log buffer). fields must be structured-clone serializable — a non-clonable value throws synchronously here, exactly like invoke/publish (it is NOT raw console).

Parameters

level

LogLevel

message

string

fields?

Record<string, unknown>

Returns

void

navigate()

navigate(opts): Promise<void>;

Ask the shell to change the top-level location. See NavigateOptions.

Parameters

opts

NavigateOptions

Returns

Promise<void>

onThemeChange()

onThemeChange(handler): () => void;

Subscribe to theme changes; returns an unsubscribe function.

Parameters

handler

(theme) => void

Returns

() => void

provide()

provide<P>(
   intent,
   version,
   handler): () => void;

Type Parameters

P

P = unknown

Parameters

intent

string

version

string

handler

IntentHandler<P>

Returns

() => void

publish()

publish(topic, payload): void;

Broadcast an ambient event (fan-out, no response).

Parameters

topic

string

payload

unknown

Returns

void

ready()

ready(): void;

Signal the app has finished bootstrapping and registered its handlers — the shell holds intent/navigation/event traffic until this is sent. Call once, after provide / subscribe / onShellNavigate are wired.

Returns

void

span()

span(name): SpanHandle;

Open a manual span under the current trace’s active span, for timing app-side work the shell can’t observe. Rarely needed — the SDK already auto-spans provide handlers. Close the handle to record it. See SpanHandle.

Parameters

name

string

Returns

SpanHandle

subscribe<P>(topic, handler): () => void;

Listen for a broadcast event; returns an unsubscribe function.

Type Parameters

P

P = unknown

Parameters

topic

string

handler

EventHandler<P>

Returns

() => void