@palettelab/sdk 0.1.21 → 0.1.23

package/README.md

@@ -366,6 +366,18 @@ 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.
 
+The model is intentionally contract-first:
+
+- Provider apps declare `provides.namespace`, `provides.services[].methods`,
+  optional JSON schemas, and `provides.events`.
+- Consumer apps declare exact qualified targets such as
+  `hr/v1#approvalChain.get` under `consumes.services` or `consumes.events`.
+- Installs use a dependency plan so required provider apps can be installed
+  first.
+- Org owners/admins can grant or revoke each consumed service/event target after
+  install.
+- Every service call and event subscription is checked again at runtime.
+
 ```tsx
 import { createPaletteClient, usePlatform } from "@palettelab/sdk"
 
@@ -378,15 +390,56 @@ const unsubscribe = palette.events.on("hr/v1#hierarchy.updated", (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 TypeScript clients that import the SDK's default
-`palette` client and write calls such as `palette.broker.call(...)` under
-`.palette/types/services.ts`.
+`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`.
+
+In Palette native runtime, the SDK calls `/api/v1/os-broker/dispatch` and
+`/api/v1/os-broker/events/stream` directly with the current app identity. In
+iframe sandbox runtime, the SDK sends `palette.broker.call`,
+`palette.broker.emit`, and `palette.broker.subscribe` messages to the Palette
+host. The host forwards the request through the same broker endpoints, so
+sandboxed apps still get the same manifest, install, grant, and schema checks.
+
+Declare the frontend dependency in `palette-plugin.json`:
+
+```json
+{
+  "consumes": {
+    "services": [
+      {
+        "target": "hr/v1#approvalChain.get",
+        "required": true,
+        "reason": "Route leave approvals through HR"
+      }
+    ],
+    "events": [
+      {
+        "target": "hr/v1#hierarchy.updated",
+        "required": false,
+        "reason": "Refresh approval-chain cache"
+      }
+    ]
+  }
+}
+```
+
+Generated service clients use the default exported `palette` client from the
+SDK. That lets generated files work in both app components and shared modules:
+
+```ts
+import { hr } from "./.palette/types/services"
+
+const chain = await hr.approvalChain.get({ user_id })
+```
 
 ### Data Room Folders By Name
 

package/dist/index.d.mts

@@ -137,6 +137,8 @@ type EventMeta = {
 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[];
 };
@@ -165,6 +167,12 @@ declare class BrokerCallError extends Error {
     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;
@@ -354,6 +362,8 @@ declare function createPaletteClient(ctx?: PlatformContext): {
     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[];
     };
 };
@@ -399,6 +409,8 @@ declare const palette: {
     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[];
     };
 };
@@ -407,4 +419,4 @@ declare function hasPermission(ctx: PlatformContext, permission: string): boolea
 declare function hasAnyPermission(ctx: PlatformContext, permissions: string[]): boolean;
 declare function hasAllPermissions(ctx: PlatformContext, permissions: string[]): boolean;
 
-export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, 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 };
+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

@@ -137,6 +137,8 @@ type EventMeta = {
 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[];
 };
@@ -165,6 +167,12 @@ declare class BrokerCallError extends Error {
     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;
@@ -354,6 +362,8 @@ declare function createPaletteClient(ctx?: PlatformContext): {
     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[];
     };
 };
@@ -399,6 +409,8 @@ declare const palette: {
     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[];
     };
 };
@@ -407,4 +419,4 @@ declare function hasPermission(ctx: PlatformContext, permission: string): boolea
 declare function hasAnyPermission(ctx: PlatformContext, permissions: string[]): boolean;
 declare function hasAllPermissions(ctx: PlatformContext, permissions: string[]): boolean;
 
-export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, 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 };
+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.js

@@ -21,8 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   BrokerCallError: () => BrokerCallError,
+  CrossAppGrantError: () => CrossAppGrantError,
   DataRoomClient: () => DataRoomClient,
   Link: () => Link,
+  MissingDependencyError: () => MissingDependencyError,
   OrganizationClient: () => OrganizationClient,
   PaletteApiError: () => PaletteApiError,
   PaletteAppRouter: () => PaletteAppRouter,
@@ -399,6 +401,28 @@ var BrokerCallError = class extends Error {
     this.name = "BrokerCallError";
   }
 };
+var MissingDependencyError = class extends BrokerCallError {
+  constructor(message, target, status) {
+    super(message, target, status);
+    this.name = "MissingDependencyError";
+  }
+};
+var CrossAppGrantError = class extends BrokerCallError {
+  constructor(message, target, status) {
+    super(message, target, status);
+    this.name = "CrossAppGrantError";
+  }
+};
+function brokerError(message, target, status) {
+  const lower = message.toLowerCase();
+  if (status === 424 || lower.includes("not installed") || lower.includes("provider app")) {
+    return new MissingDependencyError(message, target, status);
+  }
+  if (status === 403 && (lower.includes("grant") || lower.includes("declared"))) {
+    return new CrossAppGrantError(message, target, status);
+  }
+  return new BrokerCallError(message, target, status);
+}
 var CALLER_HEADER = "X-Palette-Caller-App";
 function currentPluginId() {
   if (typeof window === "undefined") return void 0;
@@ -409,12 +433,18 @@ async function brokerCallDirect(target, payload, options = {}) {
   const callerAppId = options.callerAppId ?? currentPluginId();
   const headers = {};
   if (callerAppId) headers[CALLER_HEADER] = callerAppId;
-  const res = await apiFetch("/api/v1/os-broker/dispatch", {
-    method: "POST",
-    headers,
-    body: JSON.stringify({ target, payload: payload ?? {}, caller_app_id: callerAppId }),
-    signal: options.signal
-  });
+  let res;
+  try {
+    res = await apiFetch("/api/v1/os-broker/dispatch", {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ target, payload: payload ?? {}, caller_app_id: callerAppId }),
+      signal: options.signal
+    });
+  } catch (error) {
+    const e = error;
+    throw brokerError(typeof e.detail === "string" ? e.detail : e.message, target, e.status);
+  }
   if (!res.ok) {
     let detail;
     try {
@@ -422,7 +452,7 @@ async function brokerCallDirect(target, payload, options = {}) {
     } catch {
       detail = res.statusText;
     }
-    throw new BrokerCallError(detail ?? `broker dispatch failed: ${res.status}`, target, res.status);
+    throw brokerError(detail ?? `broker dispatch failed: ${res.status}`, target, res.status);
   }
   const body = await res.json();
   return body.result;
@@ -535,7 +565,7 @@ function streamUrl() {
   const callerAppId = currentPluginId2();
   if (callerAppId) params.set("caller_app_id", callerAppId);
   const query = params.toString();
-  return `/api/v1/os-broker/events/stream${query ? `?${query}` : ""}`;
+  return `${getBaseUrl()}/api/v1/os-broker/events/stream${query ? `?${query}` : ""}`;
 }
 function ensureStream() {
   if (activeStream || typeof window === "undefined") return;
@@ -616,6 +646,12 @@ var events = {
   async emit(target, payload) {
     await broker.emit(target, payload);
   },
+  async publishDurable(target, payload) {
+    await broker.emit(target, payload);
+  },
+  async emitDurable(target, payload) {
+    await broker.emit(target, payload);
+  },
   /** Diagnostic: list active subscriptions in this page. */
   active() {
     return Array.from(SUBSCRIBERS.keys());
@@ -1429,8 +1465,10 @@ function usePluginChat(agentId) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrokerCallError,
+  CrossAppGrantError,
   DataRoomClient,
   Link,
+  MissingDependencyError,
   OrganizationClient,
   PaletteApiError,
   PaletteAppRouter,

package/dist/index.mjs

@@ -326,6 +326,28 @@ var BrokerCallError = class extends Error {
     this.name = "BrokerCallError";
   }
 };
+var MissingDependencyError = class extends BrokerCallError {
+  constructor(message, target, status) {
+    super(message, target, status);
+    this.name = "MissingDependencyError";
+  }
+};
+var CrossAppGrantError = class extends BrokerCallError {
+  constructor(message, target, status) {
+    super(message, target, status);
+    this.name = "CrossAppGrantError";
+  }
+};
+function brokerError(message, target, status) {
+  const lower = message.toLowerCase();
+  if (status === 424 || lower.includes("not installed") || lower.includes("provider app")) {
+    return new MissingDependencyError(message, target, status);
+  }
+  if (status === 403 && (lower.includes("grant") || lower.includes("declared"))) {
+    return new CrossAppGrantError(message, target, status);
+  }
+  return new BrokerCallError(message, target, status);
+}
 var CALLER_HEADER = "X-Palette-Caller-App";
 function currentPluginId() {
   if (typeof window === "undefined") return void 0;
@@ -336,12 +358,18 @@ async function brokerCallDirect(target, payload, options = {}) {
   const callerAppId = options.callerAppId ?? currentPluginId();
   const headers = {};
   if (callerAppId) headers[CALLER_HEADER] = callerAppId;
-  const res = await apiFetch("/api/v1/os-broker/dispatch", {
-    method: "POST",
-    headers,
-    body: JSON.stringify({ target, payload: payload ?? {}, caller_app_id: callerAppId }),
-    signal: options.signal
-  });
+  let res;
+  try {
+    res = await apiFetch("/api/v1/os-broker/dispatch", {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ target, payload: payload ?? {}, caller_app_id: callerAppId }),
+      signal: options.signal
+    });
+  } catch (error) {
+    const e = error;
+    throw brokerError(typeof e.detail === "string" ? e.detail : e.message, target, e.status);
+  }
   if (!res.ok) {
     let detail;
     try {
@@ -349,7 +377,7 @@ async function brokerCallDirect(target, payload, options = {}) {
     } catch {
       detail = res.statusText;
     }
-    throw new BrokerCallError(detail ?? `broker dispatch failed: ${res.status}`, target, res.status);
+    throw brokerError(detail ?? `broker dispatch failed: ${res.status}`, target, res.status);
   }
   const body = await res.json();
   return body.result;
@@ -462,7 +490,7 @@ function streamUrl() {
   const callerAppId = currentPluginId2();
   if (callerAppId) params.set("caller_app_id", callerAppId);
   const query = params.toString();
-  return `/api/v1/os-broker/events/stream${query ? `?${query}` : ""}`;
+  return `${getBaseUrl()}/api/v1/os-broker/events/stream${query ? `?${query}` : ""}`;
 }
 function ensureStream() {
   if (activeStream || typeof window === "undefined") return;
@@ -543,6 +571,12 @@ var events = {
   async emit(target, payload) {
     await broker.emit(target, payload);
   },
+  async publishDurable(target, payload) {
+    await broker.emit(target, payload);
+  },
+  async emitDurable(target, payload) {
+    await broker.emit(target, payload);
+  },
   /** Diagnostic: list active subscriptions in this page. */
   active() {
     return Array.from(SUBSCRIBERS.keys());
@@ -1364,8 +1398,10 @@ function usePluginChat(agentId) {
 }
 export {
   BrokerCallError,
+  CrossAppGrantError,
   DataRoomClient,
   Link,
+  MissingDependencyError,
   OrganizationClient,
   PaletteApiError,
   PaletteAppRouter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/sdk",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Palette Platform SDK for building plugins and apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",