@proteos/component-sdk 0.18.1

package/src/protocol.ts

@@ -0,0 +1,103 @@
+// postMessage protocol between the host page and the component-runtime iframe.
+// This is the single source of truth for the wire contract: the host renderer
+// (clients/web .../component-frame.tsx), the runtime shell
+// (clients/web/component-runtime/shell.tsx), and the author-facing hooks
+// (this package's RuntimeProvider / useNavigate) all import these same types so
+// every end stays in lockstep.
+//
+// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated
+// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).
+
+export const MESSAGE_SOURCE = 'proteos-component-runtime' as const
+
+export interface PageContext {
+  record?: Record<string, unknown>
+  entity?: { slug: string; [key: string]: unknown }
+  params?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+// ── Host → runtime ──────────────────────────────────────────────────────────
+
+export interface InitMessage {
+  type: 'INIT'
+  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient
+   *  prepends `Bearer ` when building the Authorization header, so the host
+   *  sends the token verbatim — NOT a full `Bearer …` header value. */
+  authToken: string
+  /** API origin the bundle endpoint + SDK calls resolve against. */
+  apiBaseUrl: string
+  /** Resolved props for the component (Liquid templating happens host-side). */
+  props: Record<string, unknown>
+  pageCtx: PageContext
+}
+
+export interface AuthRefreshMessage {
+  type: 'AUTH_REFRESH'
+  token: string
+}
+
+export interface DataInvalidateMessage {
+  type: 'DATA_INVALIDATE'
+  queryKey?: unknown[]
+}
+
+export type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage
+
+// ── Runtime → host ──────────────────────────────────────────────────────────
+
+export interface ReadyMessage {
+  type: 'READY'
+}
+
+export interface ResizeMessage {
+  type: 'RESIZE'
+  height: number
+}
+
+export interface NavigateMessage {
+  type: 'NAVIGATE'
+  to: string
+}
+
+/** Open an in-app path in a peek (slide-over) panel instead of full-page
+ *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides
+ *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */
+export interface OpenPeekMessage {
+  type: 'OPEN_PEEK'
+  to: string
+}
+
+export interface ErrorMessage {
+  type: 'ERROR'
+  message: string
+  stack?: string
+}
+
+export type RuntimeMessage =
+  | ReadyMessage
+  | ResizeMessage
+  | NavigateMessage
+  | OpenPeekMessage
+  | ErrorMessage
+
+// Wire envelope: the message plus the source discriminator.
+export type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }
+
+export function isHostMessage(data: unknown): data is Envelope<HostMessage> {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    (data as { source?: unknown }).source === MESSAGE_SOURCE &&
+    typeof (data as { type?: unknown }).type === 'string'
+  )
+}
+
+export function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    (data as { source?: unknown }).source === MESSAGE_SOURCE &&
+    typeof (data as { type?: unknown }).type === 'string'
+  )
+}