@palettelab/sdk 0.1.20 → 0.1.22

package/README.md

@@ -122,8 +122,20 @@ import {
   PluginProvider,
   usePlatform,
   createPaletteClient,
+  palette,
   DataRoomClient,
+  dataRooms,
   StorageClient,
+  UserClient,
+  OrganizationClient,
+  getConnections,
+  startConnection,
+  disconnectConnection,
+  requireConnection,
+  broker,
+  servicesProxy,
+  BrokerCallError,
+  events,
   usePluginTranslations,
   translate,
   normalizePaletteLanguage,
@@ -162,12 +174,14 @@ import { PluginProvider } from "@palettelab/sdk/components"
 Public frontend helpers exported by `@palettelab/sdk`:
 
 - Provider/context: `PluginProvider`, `usePlatform`, `PlatformCtx`.
-- Client facade: `createPaletteClient(platform?)`.
+- Client facade: `createPaletteClient(platform?)`; `palette` is the default no-argument client used by generated broker clients.
 - API: `apiFetch(path, init?)`, `apiUpload(path, file, fieldName?, extraFields?)`, `setBaseUrl(url)`, `getBaseUrl()`.
 - Errors: `PaletteApiError`, `errorFromResponse(response)`, `isPaletteApiError(error)`.
 - Data Rooms: `DataRoomClient`, `dataRooms`, plus `list`, `create`, `get`, `folder`, `ensureRoom`, `requireRoomByName`, `findRoomByName`, `createFolder`, `ensureFolder`, `findFolderByName`, `resolveFolderPath`, `findFileByName`, `requestUpload`, `confirmUpload`, and `uploadFile`.
 - Storage: `StorageClient`, `upload(file, options)`, `resume(file, options)`, and `uploadToSignedUrl(uploadUrl, file, contentType?)`.
 - Install config: `getInstallConfig(pluginId)`, `updateInstallConfig(pluginId, values)`.
+- Connections: `getConnections(pluginId)`, `startConnection(pluginId, connectionId)`, `disconnectConnection(pluginId, connectionId)`, and `requireConnection(pluginId, connectionId)`.
+- App-to-app broker: `broker.call(target, payload?)`, `broker.emit(target, payload?)`, `servicesProxy(namespaceVersion)`, `events.on(target, handler)`, `events.emit(target, payload?)`, and `BrokerCallError`.
 - Organization/user: `UserClient`, `OrganizationClient`, including `current`, `updateProfile`, `listMine`, `listMembers`, `getMember`, `getMemberByEmail`, `inviteMember`, and `updateMemberRole`.
 - Permissions: `hasPermission(ctx, permission)`, `hasAnyPermission(ctx, permissions)`, `hasAllPermissions(ctx, permissions)`.
 - Translations: `normalizePaletteLanguage`, `translate`, `usePluginTranslations`.
@@ -311,6 +325,7 @@ Included clients:
 - `palette.organization.currentId()`, `currentRole()`, `listMine()`, `listMembers()`, `getMember()`, `getMemberByEmail()`, `inviteMember()`, and `updateMemberRole()`
 - `palette.dataRooms.list()`, `create()`, `get()`, `folder()`, `createFolder()`, `ensureFolder()`, `findRoomByName()`, `findFolderByName()`, `resolveFolderPath()`, `findFileByName()`, and `uploadFile()`
 - `palette.config.get()` and `palette.config.update(values)`, with optional plugin ID override
+- `palette.connections.list()`, `connect()`, `disconnect()`, and `require()`
 - `palette.permissions.has()`, `hasAny()`, and `hasAll()`
 - `palette.storage.upload(file, options)`, `resume(file, options)`, and `uploadToSignedUrl()`
 - `palette.toast.success()`, `error()`, and `info()`
@@ -344,6 +359,37 @@ updates. When the runtime provides declared app permissions, these helpers check
 those permissions before calling the platform API. Member deletion/removal is
 intentionally not exposed through the app SDK.
 
+### App-To-App Broker
+
+Frontend apps can call declared broker services and subscribe to declared broker
+events through the SDK. The app manifest must list the targets under
+`consumes.services` or `consumes.events`; Palette checks the manifest and the
+org install grant before dispatching.
+
+```tsx
+import { createPaletteClient, usePlatform } from "@palettelab/sdk"
+
+const palette = createPaletteClient(usePlatform())
+
+const chain = await palette.services("hr/v1").approvalChain.get({ user_id })
+
+const unsubscribe = palette.events.on("hr/v1#hierarchy.updated", (payload) => {
+  console.log(payload)
+})
+
+await palette.events.emit("leave/v1#leave.requested", { user_id, chain })
+await palette.events.publishDurable("leave/v1#leave.requested", { user_id, chain })
+unsubscribe()
+```
+
+Use `palette.broker.call("hr/v1#approvalChain.get", payload)` for a low-level
+call when a generated helper is not available.
+
+`pltt services pull` generates nested TypeScript clients under
+`.palette/types/services.ts`, so app code can import helpers instead of
+managing target strings by hand. Broker failures are surfaced as
+`MissingDependencyError`, `CrossAppGrantError`, or `BrokerCallError`.
+
 ### Data Room Folders By Name
 
 Apps can create or reuse custom Data Room folders by name:

package/dist/components/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import react__default from 'react';
-import { P as PlatformContext } from '../plugin-dpLzOtF6.mjs';
+import { P as PlatformContext } from '../plugin-DXqw6d0s.mjs';
 
 /**
  * Provider that wraps plugin components with the platform context.

package/dist/components/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import react__default from 'react';
-import { P as PlatformContext } from '../plugin-dpLzOtF6.js';
+import { P as PlatformContext } from '../plugin-DXqw6d0s.js';
 
 /**
  * Provider that wraps plugin components with the platform context.

package/dist/hooks/index.d.mts

@@ -1,4 +1,4 @@
-export { P as PlatformCtx, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from '../index-DsfTFnZb.mjs';
+export { P as PlatformCtx, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from '../index-CmY9M7Rg.mjs';
 import 'react';
-import '../plugin-dpLzOtF6.mjs';
+import '../plugin-DXqw6d0s.mjs';
 import '../data-room-Dtd9LLHf.mjs';

package/dist/hooks/index.d.ts

@@ -1,4 +1,4 @@
-export { P as PlatformCtx, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from '../index-D0i35Hem.js';
+export { P as PlatformCtx, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from '../index-CGSwI4TZ.js';
 import 'react';
-import '../plugin-dpLzOtF6.js';
+import '../plugin-DXqw6d0s.js';
 import '../data-room-Dtd9LLHf.js';

package/dist/{index-D0i35Hem.d.ts → index-CGSwI4TZ.d.ts}

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { d as PaletteLanguage, P as PlatformContext } from './plugin-dpLzOtF6.js';
+import { d as PaletteLanguage, P as PlatformContext } from './plugin-DXqw6d0s.js';
 import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, a as DataRoomFolder, b as DataRoomFile, d as ChatThread, c as ChatMessage } from './data-room-Dtd9LLHf.js';
 
 type TranslationPrimitive = string | number | boolean | null;

package/dist/{index-DsfTFnZb.d.mts → index-CmY9M7Rg.d.mts}

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { d as PaletteLanguage, P as PlatformContext } from './plugin-dpLzOtF6.mjs';
+import { d as PaletteLanguage, P as PlatformContext } from './plugin-DXqw6d0s.mjs';
 import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, a as DataRoomFolder, b as DataRoomFile, d as ChatThread, c as ChatMessage } from './data-room-Dtd9LLHf.mjs';
 
 type TranslationPrimitive = string | number | boolean | null;

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { P as PlatformContext, O as OrgSummary, U as User } from './plugin-dpLzOtF6.mjs';
-export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, d as PaletteLanguage, e as PluginAgentDefinition, f as PluginComponentProps, g as PluginConnectionDefinition, h as PluginManifest, i as PluginToolDefinition } from './plugin-dpLzOtF6.mjs';
+import { P as PlatformContext, O as OrgSummary, U as User } from './plugin-DXqw6d0s.mjs';
+export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, d as PaletteLanguage, e as PluginAgentDefinition, f as PluginComponentProps, g as PluginConnectionDefinition, h as PluginManifest, i as PluginToolDefinition } from './plugin-DXqw6d0s.mjs';
 import { D as DataRoom, a as DataRoomFolder, b as DataRoomFile } from './data-room-Dtd9LLHf.mjs';
 export { C as ChatAttachment, c as ChatMessage, d as ChatThread, e as DataRoomPermission, T as Task, f as TaskAgentSnippet, g as TaskCreatePayload, h as TaskPriority, i as TaskStats, j as TaskStatus, k as TaskType, l as TaskUpdatePayload } from './data-room-Dtd9LLHf.mjs';
 export { AgentResource, ResourcesByGroup } from './types/index.mjs';
 import { ReactElement } from 'react';
-export { P as PlatformCtx, T as TranslateOptions, a as TranslationDictionary, b as TranslationPrimitive, c as TranslationResources, d as TranslationValues, U as UsePluginTranslationsOptions, n as normalizePaletteLanguage, t as translate, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from './index-DsfTFnZb.mjs';
+export { P as PlatformCtx, T as TranslateOptions, a as TranslationDictionary, b as TranslationPrimitive, c as TranslationResources, d as TranslationValues, U as UsePluginTranslationsOptions, n as normalizePaletteLanguage, t as translate, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from './index-CmY9M7Rg.mjs';
 export { Link, PaletteAppRoute, PaletteAppRouter, notFound, useParams, usePathname, useRouter, useSearchParams } from './router/index.mjs';
 export { PluginProvider } from './components/index.mjs';
 import 'react/jsx-runtime';
@@ -40,6 +40,37 @@ declare function errorFromResponse(response: Response): Promise<PaletteApiError>
 declare function isPaletteApiError(error: unknown): error is PaletteApiError;
 
 type ToastType = "success" | "error" | "info";
+/**
+ * Broker message kinds the host page must proxy on behalf of sandboxed iframe
+ * apps. Each message carries a unique `id` for request/response correlation.
+ *
+ *  - `palette.broker.call`      → host POSTs /api/v1/os-broker/dispatch, replies `{ id, result | error }`.
+ *  - `palette.broker.emit`      → host POSTs /api/v1/os-broker/events/emit,  replies `{ id, error? }`.
+ *  - `palette.broker.subscribe` → host adds the target to its SSE stream; events arrive as `palette.broker.event` messages.
+ *  - `palette.broker.unsubscribe` → host removes the target.
+ *
+ *  Events from the host to the guest use the `palette.broker.event` message
+ *  shape `{ kind, target, payload, meta }`.
+ */
+type SandboxBrokerMessage = {
+    kind: "palette.broker.call";
+    id: string;
+    target: string;
+    payload: unknown;
+    callerAppId?: string;
+} | {
+    kind: "palette.broker.emit";
+    id: string;
+    target: string;
+    payload: unknown;
+    callerAppId?: string;
+} | {
+    kind: "palette.broker.subscribe";
+    target: string;
+} | {
+    kind: "palette.broker.unsubscribe";
+    target: string;
+};
 type SandboxBridge = {
     apiFetch: PlatformContext["apiFetch"];
     navigate: (path: string) => void;
@@ -82,6 +113,80 @@ declare function requireConnection(pluginId: string, connectionId: string): Prom
 declare function createMockPlatformContext(overrides?: Partial<PlatformContext>): PlatformContext;
 declare function withPluginProvider(element: ReactElement, platform?: Partial<PlatformContext>): ReactElement;
 
+/**
+ * OS broker events — subscribe + emit.
+ *
+ *   import { palette } from "@palettelab/sdk"
+ *
+ *   const unsubscribe = palette.events.on("org/v1#member.updated", (payload) => {
+ *     // ...
+ *   })
+ *
+ *   await palette.events.emit("hr/v1#review.completed", { user_id: 42 })
+ *
+ * Subscriptions ride a single SSE connection to `GET /api/v1/os-broker/events/stream`.
+ * Sandboxed iframe apps subscribe via the host page's postMessage bridge.
+ */
+
+type Handler = (payload: unknown, meta: EventMeta) => void;
+type EventMeta = {
+    target: string;
+    organizationId: number | null;
+    occurredAt: string;
+};
+declare const events: {
+    on(target: string, handler: Handler): () => void;
+    emit(target: string, payload?: unknown): Promise<void>;
+    publishDurable(target: string, payload?: unknown): Promise<void>;
+    emitDurable(target: string, payload?: unknown): Promise<void>;
+    /** Diagnostic: list active subscriptions in this page. */
+    active(): string[];
+};
+
+/**
+ * OS broker client — request/response helpers.
+ *
+ *   import { palette } from "@palettelab/sdk"
+ *
+ *   const { items } = await palette.services("org/v1").members.list({ team_id: 7 })
+ *
+ *   // or, untyped low-level form:
+ *   const result = await palette.broker.call("org/v1#members.list", { team_id: 7 })
+ *
+ * Apps never know each other's URLs. Every call hits the broker, which checks
+ * the consumer's manifest `consumes` block and the org admin's grant before
+ * dispatching to the provider in-process (or, for out-of-process backends,
+ * via the platform's signed internal-call transport).
+ *
+ * In a sandboxed iframe app, the SDK forwards the call to the parent host
+ * page via postMessage rather than calling the broker endpoint directly —
+ * the host is the only frame holding the session cookie.
+ */
+declare class BrokerCallError extends Error {
+    readonly target: string;
+    readonly status?: number | undefined;
+    constructor(message: string, target: string, status?: number | undefined);
+}
+declare class MissingDependencyError extends BrokerCallError {
+    constructor(message: string, target: string, status?: number);
+}
+declare class CrossAppGrantError extends BrokerCallError {
+    constructor(message: string, target: string, status?: number);
+}
+type BrokerCallOptions = {
+    /** Override the caller app id sent to the broker. Inferred from the URL when omitted. */
+    callerAppId?: string;
+    /** AbortSignal forwarded to fetch. */
+    signal?: AbortSignal;
+};
+/** Low-level broker API. Prefer the typed `palette.services(...)` proxy. */
+declare const broker: {
+    call(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<unknown>;
+    emit(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<void>;
+};
+/** Typed proxy: `palette.services("org/v1").members.list({ ... })`. */
+declare function servicesProxy(namespaceVersion: string): any;
+
 interface DataRoomContents {
     room?: DataRoom;
     folders: DataRoomFolder[];
@@ -241,11 +346,77 @@ declare function createPaletteClient(ctx?: PlatformContext): {
         error: (message: string) => void | undefined;
         info: (message: string) => void | undefined;
     };
+    /**
+     * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
+     * The proxy resolves a dotted method chain into a qualified target string
+     * and dispatches via the broker (in-process for plugins on the host,
+     * postMessage for sandboxed iframe apps).
+     */
+    services: (namespaceVersion: string) => any;
+    /** Low-level broker accessor when you don't want the typed proxy. */
+    broker: {
+        call(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<unknown>;
+        emit(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<void>;
+    };
+    /** OS-broker pub/sub. `events.on(target, fn)` returns an unsubscribe function. */
+    events: {
+        on(target: string, handler: (payload: unknown, meta: EventMeta) => void): () => void;
+        emit(target: string, payload?: unknown): Promise<void>;
+        publishDurable(target: string, payload?: unknown): Promise<void>;
+        emitDurable(target: string, payload?: unknown): Promise<void>;
+        active(): string[];
+    };
 };
 type PaletteClient = ReturnType<typeof createPaletteClient>;
+declare const palette: {
+    user: UserClient;
+    organization: OrganizationClient;
+    dataRooms: DataRoomClient;
+    storage: StorageClient;
+    config: {
+        get: (pluginId?: string) => Promise<InstallConfig>;
+        update: (values: Record<string, unknown>, pluginId?: string) => Promise<InstallConfig>;
+    };
+    connections: {
+        list: (pluginId?: string) => Promise<ConnectionStatus[]>;
+        connect: (connectionId: string, pluginId?: string) => Promise<ConnectionAuthStart>;
+        disconnect: (connectionId: string, pluginId?: string) => Promise<void>;
+        require: (connectionId: string, pluginId?: string) => Promise<ConnectionStatus>;
+    };
+    permissions: {
+        has: (permission: string) => boolean;
+        hasAny: (permissions: string[]) => boolean;
+        hasAll: (permissions: string[]) => boolean;
+    };
+    toast: {
+        success: (message: string) => void | undefined;
+        error: (message: string) => void | undefined;
+        info: (message: string) => void | undefined;
+    };
+    /**
+     * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
+     * The proxy resolves a dotted method chain into a qualified target string
+     * and dispatches via the broker (in-process for plugins on the host,
+     * postMessage for sandboxed iframe apps).
+     */
+    services: (namespaceVersion: string) => any;
+    /** Low-level broker accessor when you don't want the typed proxy. */
+    broker: {
+        call(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<unknown>;
+        emit(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<void>;
+    };
+    /** OS-broker pub/sub. `events.on(target, fn)` returns an unsubscribe function. */
+    events: {
+        on(target: string, handler: (payload: unknown, meta: EventMeta) => void): () => void;
+        emit(target: string, payload?: unknown): Promise<void>;
+        publishDurable(target: string, payload?: unknown): Promise<void>;
+        emitDurable(target: string, payload?: unknown): Promise<void>;
+        active(): string[];
+    };
+};
 
 declare function hasPermission(ctx: PlatformContext, permission: string): boolean;
 declare function hasAnyPermission(ctx: PlatformContext, permissions: string[]): boolean;
 declare function hasAllPermissions(ctx: PlatformContext, permissions: string[]): boolean;
 
-export { type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type InstallConfig, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, requireConnection, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };
+export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, CrossAppGrantError, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, MissingDependencyError, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, type SandboxBrokerMessage, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, broker, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, events, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, palette, requireConnection, servicesProxy, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { P as PlatformContext, O as OrgSummary, U as User } from './plugin-dpLzOtF6.js';
-export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, d as PaletteLanguage, e as PluginAgentDefinition, f as PluginComponentProps, g as PluginConnectionDefinition, h as PluginManifest, i as PluginToolDefinition } from './plugin-dpLzOtF6.js';
+import { P as PlatformContext, O as OrgSummary, U as User } from './plugin-DXqw6d0s.js';
+export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, d as PaletteLanguage, e as PluginAgentDefinition, f as PluginComponentProps, g as PluginConnectionDefinition, h as PluginManifest, i as PluginToolDefinition } from './plugin-DXqw6d0s.js';
 import { D as DataRoom, a as DataRoomFolder, b as DataRoomFile } from './data-room-Dtd9LLHf.js';
 export { C as ChatAttachment, c as ChatMessage, d as ChatThread, e as DataRoomPermission, T as Task, f as TaskAgentSnippet, g as TaskCreatePayload, h as TaskPriority, i as TaskStats, j as TaskStatus, k as TaskType, l as TaskUpdatePayload } from './data-room-Dtd9LLHf.js';
 export { AgentResource, ResourcesByGroup } from './types/index.js';
 import { ReactElement } from 'react';
-export { P as PlatformCtx, T as TranslateOptions, a as TranslationDictionary, b as TranslationPrimitive, c as TranslationResources, d as TranslationValues, U as UsePluginTranslationsOptions, n as normalizePaletteLanguage, t as translate, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from './index-D0i35Hem.js';
+export { P as PlatformCtx, T as TranslateOptions, a as TranslationDictionary, b as TranslationPrimitive, c as TranslationResources, d as TranslationValues, U as UsePluginTranslationsOptions, n as normalizePaletteLanguage, t as translate, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from './index-CGSwI4TZ.js';
 export { Link, PaletteAppRoute, PaletteAppRouter, notFound, useParams, usePathname, useRouter, useSearchParams } from './router/index.js';
 export { PluginProvider } from './components/index.js';
 import 'react/jsx-runtime';
@@ -40,6 +40,37 @@ declare function errorFromResponse(response: Response): Promise<PaletteApiError>
 declare function isPaletteApiError(error: unknown): error is PaletteApiError;
 
 type ToastType = "success" | "error" | "info";
+/**
+ * Broker message kinds the host page must proxy on behalf of sandboxed iframe
+ * apps. Each message carries a unique `id` for request/response correlation.
+ *
+ *  - `palette.broker.call`      → host POSTs /api/v1/os-broker/dispatch, replies `{ id, result | error }`.
+ *  - `palette.broker.emit`      → host POSTs /api/v1/os-broker/events/emit,  replies `{ id, error? }`.
+ *  - `palette.broker.subscribe` → host adds the target to its SSE stream; events arrive as `palette.broker.event` messages.
+ *  - `palette.broker.unsubscribe` → host removes the target.
+ *
+ *  Events from the host to the guest use the `palette.broker.event` message
+ *  shape `{ kind, target, payload, meta }`.
+ */
+type SandboxBrokerMessage = {
+    kind: "palette.broker.call";
+    id: string;
+    target: string;
+    payload: unknown;
+    callerAppId?: string;
+} | {
+    kind: "palette.broker.emit";
+    id: string;
+    target: string;
+    payload: unknown;
+    callerAppId?: string;
+} | {
+    kind: "palette.broker.subscribe";
+    target: string;
+} | {
+    kind: "palette.broker.unsubscribe";
+    target: string;
+};
 type SandboxBridge = {
     apiFetch: PlatformContext["apiFetch"];
     navigate: (path: string) => void;
@@ -82,6 +113,80 @@ declare function requireConnection(pluginId: string, connectionId: string): Prom
 declare function createMockPlatformContext(overrides?: Partial<PlatformContext>): PlatformContext;
 declare function withPluginProvider(element: ReactElement, platform?: Partial<PlatformContext>): ReactElement;
 
+/**
+ * OS broker events — subscribe + emit.
+ *
+ *   import { palette } from "@palettelab/sdk"
+ *
+ *   const unsubscribe = palette.events.on("org/v1#member.updated", (payload) => {
+ *     // ...
+ *   })
+ *
+ *   await palette.events.emit("hr/v1#review.completed", { user_id: 42 })
+ *
+ * Subscriptions ride a single SSE connection to `GET /api/v1/os-broker/events/stream`.
+ * Sandboxed iframe apps subscribe via the host page's postMessage bridge.
+ */
+
+type Handler = (payload: unknown, meta: EventMeta) => void;
+type EventMeta = {
+    target: string;
+    organizationId: number | null;
+    occurredAt: string;
+};
+declare const events: {
+    on(target: string, handler: Handler): () => void;
+    emit(target: string, payload?: unknown): Promise<void>;
+    publishDurable(target: string, payload?: unknown): Promise<void>;
+    emitDurable(target: string, payload?: unknown): Promise<void>;
+    /** Diagnostic: list active subscriptions in this page. */
+    active(): string[];
+};
+
+/**
+ * OS broker client — request/response helpers.
+ *
+ *   import { palette } from "@palettelab/sdk"
+ *
+ *   const { items } = await palette.services("org/v1").members.list({ team_id: 7 })
+ *
+ *   // or, untyped low-level form:
+ *   const result = await palette.broker.call("org/v1#members.list", { team_id: 7 })
+ *
+ * Apps never know each other's URLs. Every call hits the broker, which checks
+ * the consumer's manifest `consumes` block and the org admin's grant before
+ * dispatching to the provider in-process (or, for out-of-process backends,
+ * via the platform's signed internal-call transport).
+ *
+ * In a sandboxed iframe app, the SDK forwards the call to the parent host
+ * page via postMessage rather than calling the broker endpoint directly —
+ * the host is the only frame holding the session cookie.
+ */
+declare class BrokerCallError extends Error {
+    readonly target: string;
+    readonly status?: number | undefined;
+    constructor(message: string, target: string, status?: number | undefined);
+}
+declare class MissingDependencyError extends BrokerCallError {
+    constructor(message: string, target: string, status?: number);
+}
+declare class CrossAppGrantError extends BrokerCallError {
+    constructor(message: string, target: string, status?: number);
+}
+type BrokerCallOptions = {
+    /** Override the caller app id sent to the broker. Inferred from the URL when omitted. */
+    callerAppId?: string;
+    /** AbortSignal forwarded to fetch. */
+    signal?: AbortSignal;
+};
+/** Low-level broker API. Prefer the typed `palette.services(...)` proxy. */
+declare const broker: {
+    call(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<unknown>;
+    emit(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<void>;
+};
+/** Typed proxy: `palette.services("org/v1").members.list({ ... })`. */
+declare function servicesProxy(namespaceVersion: string): any;
+
 interface DataRoomContents {
     room?: DataRoom;
     folders: DataRoomFolder[];
@@ -241,11 +346,77 @@ declare function createPaletteClient(ctx?: PlatformContext): {
         error: (message: string) => void | undefined;
         info: (message: string) => void | undefined;
     };
+    /**
+     * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
+     * The proxy resolves a dotted method chain into a qualified target string
+     * and dispatches via the broker (in-process for plugins on the host,
+     * postMessage for sandboxed iframe apps).
+     */
+    services: (namespaceVersion: string) => any;
+    /** Low-level broker accessor when you don't want the typed proxy. */
+    broker: {
+        call(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<unknown>;
+        emit(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<void>;
+    };
+    /** OS-broker pub/sub. `events.on(target, fn)` returns an unsubscribe function. */
+    events: {
+        on(target: string, handler: (payload: unknown, meta: EventMeta) => void): () => void;
+        emit(target: string, payload?: unknown): Promise<void>;
+        publishDurable(target: string, payload?: unknown): Promise<void>;
+        emitDurable(target: string, payload?: unknown): Promise<void>;
+        active(): string[];
+    };
 };
 type PaletteClient = ReturnType<typeof createPaletteClient>;
+declare const palette: {
+    user: UserClient;
+    organization: OrganizationClient;
+    dataRooms: DataRoomClient;
+    storage: StorageClient;
+    config: {
+        get: (pluginId?: string) => Promise<InstallConfig>;
+        update: (values: Record<string, unknown>, pluginId?: string) => Promise<InstallConfig>;
+    };
+    connections: {
+        list: (pluginId?: string) => Promise<ConnectionStatus[]>;
+        connect: (connectionId: string, pluginId?: string) => Promise<ConnectionAuthStart>;
+        disconnect: (connectionId: string, pluginId?: string) => Promise<void>;
+        require: (connectionId: string, pluginId?: string) => Promise<ConnectionStatus>;
+    };
+    permissions: {
+        has: (permission: string) => boolean;
+        hasAny: (permissions: string[]) => boolean;
+        hasAll: (permissions: string[]) => boolean;
+    };
+    toast: {
+        success: (message: string) => void | undefined;
+        error: (message: string) => void | undefined;
+        info: (message: string) => void | undefined;
+    };
+    /**
+     * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
+     * The proxy resolves a dotted method chain into a qualified target string
+     * and dispatches via the broker (in-process for plugins on the host,
+     * postMessage for sandboxed iframe apps).
+     */
+    services: (namespaceVersion: string) => any;
+    /** Low-level broker accessor when you don't want the typed proxy. */
+    broker: {
+        call(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<unknown>;
+        emit(target: string, payload?: unknown, options?: BrokerCallOptions): Promise<void>;
+    };
+    /** OS-broker pub/sub. `events.on(target, fn)` returns an unsubscribe function. */
+    events: {
+        on(target: string, handler: (payload: unknown, meta: EventMeta) => void): () => void;
+        emit(target: string, payload?: unknown): Promise<void>;
+        publishDurable(target: string, payload?: unknown): Promise<void>;
+        emitDurable(target: string, payload?: unknown): Promise<void>;
+        active(): string[];
+    };
+};
 
 declare function hasPermission(ctx: PlatformContext, permission: string): boolean;
 declare function hasAnyPermission(ctx: PlatformContext, permissions: string[]): boolean;
 declare function hasAllPermissions(ctx: PlatformContext, permissions: string[]): boolean;
 
-export { type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type InstallConfig, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, requireConnection, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };
+export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, CrossAppGrantError, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, MissingDependencyError, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, type SandboxBrokerMessage, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, broker, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, events, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, palette, requireConnection, servicesProxy, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };