@proteos/component-sdk 0.18.1

package/dist/protocol.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkSMAZA2KE_cjs = require('./chunk-SMAZA2KE.cjs');
+
+
+
+Object.defineProperty(exports, "MESSAGE_SOURCE", {
+  enumerable: true,
+  get: function () { return chunkSMAZA2KE_cjs.MESSAGE_SOURCE; }
+});
+Object.defineProperty(exports, "isHostMessage", {
+  enumerable: true,
+  get: function () { return chunkSMAZA2KE_cjs.isHostMessage; }
+});
+Object.defineProperty(exports, "isRuntimeMessage", {
+  enumerable: true,
+  get: function () { return chunkSMAZA2KE_cjs.isRuntimeMessage; }
+});
+//# sourceMappingURL=protocol.cjs.map
+//# sourceMappingURL=protocol.cjs.map

package/dist/protocol.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"protocol.cjs"}

package/dist/protocol.d.cts

@@ -0,0 +1,62 @@
+declare const MESSAGE_SOURCE: "proteos-component-runtime";
+interface PageContext {
+    record?: Record<string, unknown>;
+    entity?: {
+        slug: string;
+        [key: string]: unknown;
+    };
+    params?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+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;
+}
+interface AuthRefreshMessage {
+    type: 'AUTH_REFRESH';
+    token: string;
+}
+interface DataInvalidateMessage {
+    type: 'DATA_INVALIDATE';
+    queryKey?: unknown[];
+}
+type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage;
+interface ReadyMessage {
+    type: 'READY';
+}
+interface ResizeMessage {
+    type: 'RESIZE';
+    height: number;
+}
+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. */
+interface OpenPeekMessage {
+    type: 'OPEN_PEEK';
+    to: string;
+}
+interface ErrorMessage {
+    type: 'ERROR';
+    message: string;
+    stack?: string;
+}
+type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | ErrorMessage;
+type Envelope<T> = T & {
+    source: typeof MESSAGE_SOURCE;
+};
+declare function isHostMessage(data: unknown): data is Envelope<HostMessage>;
+declare function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage>;
+
+export { type AuthRefreshMessage, type DataInvalidateMessage, type Envelope, type ErrorMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type NavigateMessage, type OpenPeekMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };

package/dist/protocol.d.ts

@@ -0,0 +1,62 @@
+declare const MESSAGE_SOURCE: "proteos-component-runtime";
+interface PageContext {
+    record?: Record<string, unknown>;
+    entity?: {
+        slug: string;
+        [key: string]: unknown;
+    };
+    params?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+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;
+}
+interface AuthRefreshMessage {
+    type: 'AUTH_REFRESH';
+    token: string;
+}
+interface DataInvalidateMessage {
+    type: 'DATA_INVALIDATE';
+    queryKey?: unknown[];
+}
+type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage;
+interface ReadyMessage {
+    type: 'READY';
+}
+interface ResizeMessage {
+    type: 'RESIZE';
+    height: number;
+}
+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. */
+interface OpenPeekMessage {
+    type: 'OPEN_PEEK';
+    to: string;
+}
+interface ErrorMessage {
+    type: 'ERROR';
+    message: string;
+    stack?: string;
+}
+type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | ErrorMessage;
+type Envelope<T> = T & {
+    source: typeof MESSAGE_SOURCE;
+};
+declare function isHostMessage(data: unknown): data is Envelope<HostMessage>;
+declare function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage>;
+
+export { type AuthRefreshMessage, type DataInvalidateMessage, type Envelope, type ErrorMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type NavigateMessage, type OpenPeekMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };

package/dist/protocol.js

@@ -0,0 +1,3 @@
+export { MESSAGE_SOURCE, isHostMessage, isRuntimeMessage } from './chunk-NMXHDDL6.js';
+//# sourceMappingURL=protocol.js.map
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"protocol.js"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@proteos/component-sdk",
+  "version": "0.18.1",
+  "license": "Apache-2.0",
+  "description": "Typed runtime hooks for authoring Proteos custom components — the SDK you import inside a component bundle.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proteos-ai/go-sdk.git",
+    "directory": "packages/component-sdk"
+  },
+  "homepage": "https://github.com/proteos-ai/go-sdk",
+  "bugs": "https://github.com/proteos-ai/go-sdk/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./protocol": {
+      "import": {
+        "types": "./dist/protocol.d.ts",
+        "default": "./dist/protocol.js"
+      },
+      "require": {
+        "types": "./dist/protocol.d.cts",
+        "default": "./dist/protocol.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@proteos/sdk": "^0.18.1"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "@tanstack/react-query": "^5.80.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.0.2",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsup": "^8.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.4",
+    "@proteos/biome-config": "0.0.0",
+    "@proteos/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/context.tsx

@@ -0,0 +1,99 @@
+import type {
+  AccountClient,
+  AgentClient,
+  DataClient,
+  FunctionsClient,
+  KnowledgeClient,
+  MetaClient,
+  StorageClient,
+} from '@proteos/sdk'
+import { createContext, type ReactNode, useMemo } from 'react'
+
+import {
+  type Envelope,
+  MESSAGE_SOURCE,
+  type NavigateMessage,
+  type OpenPeekMessage,
+  type PageContext,
+} from './protocol'
+
+/** Options for {@link RuntimeContextValue.navigate}. */
+export interface NavigateOptions {
+  /** Open the target in a peek (slide-over) panel instead of full-page. */
+  peek?: boolean
+}
+
+/**
+ * The authenticated `@proteos/sdk` clients the runtime injects. Same instances
+ * the host app uses — pre-wired with a refreshing bearer token, so a component
+ * never touches auth headers.
+ */
+export interface ComponentSdk {
+  account: AccountClient
+  agents: AgentClient
+  data: DataClient
+  functions: FunctionsClient
+  knowledge: KnowledgeClient
+  meta: MetaClient
+  storage: StorageClient
+}
+
+/**
+ * The raw runtime payload the shell hands a component at INIT. The shell builds
+ * this; component authors read it through the hooks.
+ */
+export interface RuntimeValue {
+  sdk: ComponentSdk
+  /** Liquid-resolved props (a snapshot — not a live binding). */
+  props: Record<string, unknown>
+  /** Page context snapshot: the host record, entity, and URL params. */
+  pageCtx: PageContext
+  /** API origin SDK calls + asset URLs resolve against. */
+  apiBaseUrl: string
+  /** Current bearer token getter (escape hatch for raw fetches). */
+  getToken: () => string
+}
+
+/** Runtime value plus the derived helpers the hooks expose. */
+export interface RuntimeContextValue extends RuntimeValue {
+  /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or
+   *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */
+  navigate: (to: string, options?: NavigateOptions) => void
+}
+
+export const RuntimeContext = createContext<RuntimeContextValue | null>(null)
+
+/** Post a NAVIGATE envelope to the host. The host only honours relative,
+ *  in-app targets (it ignores absolute/external URLs). */
+function postNavigate(to: string): void {
+  const envelope: Envelope<NavigateMessage> = { source: MESSAGE_SOURCE, type: 'NAVIGATE', to }
+  window.parent?.postMessage(envelope, '*')
+}
+
+/** Post an OPEN_PEEK envelope to the host — open the in-app path in a peek
+ *  panel. Same relative-path contract as {@link postNavigate}. */
+function postOpenPeek(to: string): void {
+  const envelope: Envelope<OpenPeekMessage> = { source: MESSAGE_SOURCE, type: 'OPEN_PEEK', to }
+  window.parent?.postMessage(envelope, '*')
+}
+
+/** Navigate full-page (default) or into a peek panel (`{ peek: true }`). */
+function navigate(to: string, options?: NavigateOptions): void {
+  if (options?.peek) postOpenPeek(to)
+  else postNavigate(to)
+}
+
+/**
+ * Provides the runtime value + derived helpers to a component subtree. Mounted
+ * by the component-runtime shell around the loaded component — authors never
+ * render this themselves. Lives in `@proteos/component-sdk` (a shared,
+ * import-mapped singleton) so the context the shell provides is the very same
+ * context the component's hooks read, across the bundle boundary.
+ */
+export function RuntimeProvider({ value, children }: { value: RuntimeValue; children: ReactNode }) {
+  // The shell builds `value` once at INIT (a stable state object — clients,
+  // props and pageCtx are all set once), so memoizing on its identity recreates
+  // the context only when the runtime genuinely re-inits.
+  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate }), [value])
+  return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>
+}

package/src/global.ts

@@ -0,0 +1,19 @@
+import type { ComponentSdk } from './context'
+import type { PageContext } from './protocol'
+
+// Ambient declaration of the low-level runtime bridge the shell injects at INIT.
+// Importing `@proteos/component-sdk` anywhere registers this, so component
+// authors get a typed `window.__PROTEOS_RUNTIME__` for free and never hand-write
+// a `declare global` block. Prefer the typed hooks (`useSdk`, `usePageContext`, …);
+// the global is the back-compat / escape-hatch path.
+declare global {
+  interface Window {
+    __PROTEOS_RUNTIME__?: {
+      apiBaseUrl: string
+      getToken: () => string
+      props: Record<string, unknown>
+      pageCtx: PageContext
+      sdk: ComponentSdk
+    }
+  }
+}

package/src/hooks.test.tsx

@@ -0,0 +1,73 @@
+import { renderHook } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { RuntimeProvider, type RuntimeValue } from './context'
+import { useApiBaseUrl, useNavigate, usePageContext, useProps, useRuntime, useSdk } from './hooks'
+import { MESSAGE_SOURCE } from './protocol'
+
+// A stable stand-in for the injected SDK — the hooks only pass it through.
+const sdk = {} as RuntimeValue['sdk']
+
+function makeValue(overrides: Partial<RuntimeValue> = {}): RuntimeValue {
+  return {
+    sdk,
+    props: { title: 'Hello' },
+    pageCtx: { record: { id: 'rec_1', name: 'ACME' }, entity: { slug: 'company' } },
+    apiBaseUrl: 'https://api.test',
+    getToken: () => 'tok_123',
+    ...overrides,
+  }
+}
+
+function wrapper(value: RuntimeValue) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <RuntimeProvider value={value}>{children}</RuntimeProvider>
+  }
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('runtime hooks', () => {
+  it('useSdk / useProps / usePageContext / useApiBaseUrl expose the runtime value', () => {
+    const value = makeValue()
+    const { result } = renderHook(
+      () => ({
+        sdk: useSdk(),
+        props: useProps<{ title: string }>(),
+        ctx: usePageContext(),
+        base: useApiBaseUrl(),
+      }),
+      { wrapper: wrapper(value) },
+    )
+    expect(result.current.sdk).toBe(value.sdk)
+    expect(result.current.props.title).toBe('Hello')
+    expect(result.current.ctx.record).toEqual({ id: 'rec_1', name: 'ACME' })
+    expect(result.current.ctx.entity?.slug).toBe('company')
+    expect(result.current.base).toBe('https://api.test')
+  })
+
+  it('usePageContext().record is undefined when the page has no bound record', () => {
+    const value = makeValue({ pageCtx: { entity: { slug: 'dashboard' } } })
+    const { result } = renderHook(() => usePageContext(), { wrapper: wrapper(value) })
+    expect(result.current.record).toBeUndefined()
+  })
+
+  it('useNavigate posts a NAVIGATE envelope to the host', () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => useNavigate(), { wrapper: wrapper(makeValue()) })
+    result.current('/org/acme/record/task/42')
+    expect(post).toHaveBeenCalledWith(
+      { source: MESSAGE_SOURCE, type: 'NAVIGATE', to: '/org/acme/record/task/42' },
+      '*',
+    )
+  })
+
+  it('throws a clear error when used outside the runtime', () => {
+    // Silence the expected React error-boundary console noise.
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() => renderHook(() => useRuntime())).toThrow(/Proteos component runtime/)
+  })
+})

package/src/hooks.ts

@@ -0,0 +1,154 @@
+import { useContext, useEffect, useState } from 'react'
+
+import {
+  type ComponentSdk,
+  type NavigateOptions,
+  RuntimeContext,
+  type RuntimeContextValue,
+} from './context'
+import type { PageContext } from './protocol'
+
+/**
+ * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,
+ * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a
+ * clear error if used outside the component runtime.
+ */
+export function useRuntime(): RuntimeContextValue {
+  const ctx = useContext(RuntimeContext)
+  if (!ctx) {
+    throw new Error(
+      '@proteos/component-sdk: hooks must run inside the Proteos component runtime. ' +
+        'This usually means the component is rendered outside its iframe, or a ' +
+        'second copy of @proteos/component-sdk was bundled instead of using the ' +
+        'runtime-provided one (keep it external).',
+    )
+  }
+  return ctx
+}
+
+/** The authenticated SDK clients (account / data / functions / meta). */
+export function useSdk(): ComponentSdk {
+  return useRuntime().sdk
+}
+
+/** The component's Liquid-resolved props (a snapshot, not a live binding). */
+export function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T {
+  return useRuntime().props as T
+}
+
+/**
+ * The full page context: host `record`, `entity`, and URL `params`. The
+ * `record` is a snapshot taken at mount (`undefined` on record-less platform
+ * pages) — fetch via `useSdk().data` for anything that must stay fresh.
+ */
+export function usePageContext(): PageContext {
+  return useRuntime().pageCtx
+}
+
+/**
+ * Navigate the host SPA to an in-app path, e.g.
+ * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external
+ * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.
+ *
+ * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead
+ * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host
+ * peeks what it can (today: platform pages) and falls back to full navigation.
+ */
+export function useNavigate(): (to: string, options?: NavigateOptions) => void {
+  return useRuntime().navigate
+}
+
+/** The API origin SDK calls resolve against (for building raw asset URLs). */
+export function useApiBaseUrl(): string {
+  return useRuntime().apiBaseUrl
+}
+
+/**
+ * A getter for the current bearer token. Returns a function (not the token)
+ * because the token is refreshed in place — read it at call time for a raw
+ * `fetch`. Most components never need this; prefer `useSdk()`.
+ */
+export function useAuthToken(): () => string {
+  return useRuntime().getToken
+}
+
+export interface HostLocation {
+  /** The host tab's pathname (same-origin read), or null if unavailable. */
+  pathname: string | null
+  /** The org id parsed from `/org/<orgId>/…`, or null. */
+  orgId: string | null
+  /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */
+  appBasePath: string | null
+}
+
+function readHostLocation(): HostLocation {
+  const empty: HostLocation = { pathname: null, orgId: null, appBasePath: null }
+  try {
+    const parentWindow = window.parent
+    if (!parentWindow || parentWindow === window) return empty
+    const pathname = parentWindow.location.pathname
+    const appMatch = pathname.match(/^\/org\/[^/]+\/app\/[^/]+/)
+    const orgMatch = pathname.match(/^\/org\/([^/]+)\//)
+    return {
+      pathname,
+      orgId: orgMatch ? (orgMatch[1] ?? null) : null,
+      appBasePath: appMatch ? appMatch[0] : null,
+    }
+  } catch {
+    // Cross-origin (untrusted-component future) or detached — fall back to null.
+    return empty
+  }
+}
+
+/**
+ * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`
+ * prefix needed to build navigation targets on platform pages. Read once on
+ * mount (the iframe re-inits when the host route changes).
+ */
+export function useHostLocation(): HostLocation {
+  const [loc] = useState(readHostLocation)
+  return loc
+}
+
+export interface FillViewportOptions {
+  /** Gap left below the component (px). Default 24. */
+  bottomMargin?: number
+  /** Floor for the computed height (px). Default 320. */
+  minHeight?: number
+}
+
+/**
+ * Compute a "fill the rest of the viewport" height for full-bleed layouts
+ * (boards, canvases). The runtime auto-sizes the iframe to its content, so a
+ * component can't use its own `vh` units (circular). The iframe is same-origin,
+ * so this measures the parent viewport minus the iframe's offset instead.
+ * Returns `null` when it can't measure (fall back to natural height).
+ */
+export function useFillViewportHeight(options: FillViewportOptions = {}): number | null {
+  const { bottomMargin = 24, minHeight = 320 } = options
+  const [height, setHeight] = useState<number | null>(null)
+
+  useEffect(() => {
+    function compute(): void {
+      try {
+        const frame = window.frameElement
+        const parentWindow = window.parent
+        if (!frame || !parentWindow || parentWindow === window) return
+        const available =
+          parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin
+        setHeight(Math.max(available, minHeight))
+      } catch {
+        setHeight(null) // cross-origin or detached — fall back to natural height
+      }
+    }
+    compute()
+    try {
+      window.parent.addEventListener('resize', compute)
+      return () => window.parent.removeEventListener('resize', compute)
+    } catch {
+      return
+    }
+  }, [bottomMargin, minHeight])
+
+  return height
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// @proteos/component-sdk — the author-facing runtime SDK for Proteos custom
+// components. Import the hooks inside a component bundle; the runtime shell
+// wires the provider. Kept EXTERNAL in both the shell build and the component
+// build (resolved via the runtime import map) so the provider and the hooks
+// share one context instance across the iframe bundle boundary.
+
+// Register the ambient `Window.__PROTEOS_RUNTIME__` augmentation.
+import './global'
+
+export type { ComponentSdk, NavigateOptions, RuntimeContextValue, RuntimeValue } from './context'
+export { RuntimeProvider } from './context'
+export type { FillViewportOptions, HostLocation } from './hooks'
+export {
+  useApiBaseUrl,
+  useAuthToken,
+  useFillViewportHeight,
+  useHostLocation,
+  useNavigate,
+  usePageContext,
+  useProps,
+  useRuntime,
+  useSdk,
+} from './hooks'
+export {
+  type AuthRefreshMessage,
+  type DataInvalidateMessage,
+  type Envelope,
+  type ErrorMessage,
+  type HostMessage,
+  type InitMessage,
+  isHostMessage,
+  isRuntimeMessage,
+  MESSAGE_SOURCE,
+  type NavigateMessage,
+  type OpenPeekMessage,
+  type PageContext,
+  type ReadyMessage,
+  type ResizeMessage,
+  type RuntimeMessage,
+} from './protocol'