@palettelab/sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,163 @@
+# @palettelab/sdk
+
+Frontend SDK for building Palette plugins and internal apps.
+
+Use this package from plugin frontends created with `@palettelab/cli`. It provides typed platform context, authenticated API helpers, React hooks for common Palette resources, iframe sandbox bridge helpers, install configuration helpers, and test utilities.
+
+## Install
+
+```bash
+npm install @palettelab/sdk react react-dom
+```
+
+`react` and `react-dom` are peer dependencies. Plugin bundles should externalize React and `@palettelab/sdk`; the Palette CLI handles this for standard templates.
+
+## Exports
+
+```ts
+import {
+  PluginProvider,
+  usePlatform,
+  usePluginTasks,
+  usePluginDataRooms,
+  usePluginChat,
+  apiFetch,
+  apiUpload,
+  createSandboxBridge,
+  getInstallConfig,
+  updateInstallConfig,
+} from "@palettelab/sdk"
+```
+
+Subpath exports are also available:
+
+```ts
+import { usePlatform } from "@palettelab/sdk/hooks"
+import type { PluginManifest } from "@palettelab/sdk/types"
+import { PluginProvider } from "@palettelab/sdk/components"
+```
+
+## Plugin Root
+
+The platform passes plugin runtime context into your root component. Wrap your UI with `PluginProvider` so hooks can read it.
+
+```tsx
+import { PluginProvider, usePlatform, type PluginComponentProps } from "@palettelab/sdk"
+
+function App() {
+  const { user, organizationId, pluginId } = usePlatform()
+
+  return (
+    <main>
+      <h1>{pluginId}</h1>
+      <p>{user?.email}</p>
+      <p>Organization: {organizationId}</p>
+    </main>
+  )
+}
+
+export default function PluginRoot(props: PluginComponentProps) {
+  return (
+    <PluginProvider value={props}>
+      <App />
+    </PluginProvider>
+  )
+}
+```
+
+## API Helpers
+
+Use `apiFetch` for authenticated platform API calls. It includes credentials and performs the platform refresh flow for normal portal runtime.
+
+```ts
+import { apiFetch } from "@palettelab/sdk"
+
+const res = await apiFetch("/api/v1/tasks")
+const tasks = await res.json()
+```
+
+Use `apiUpload` for multipart uploads.
+
+```ts
+import { apiUpload } from "@palettelab/sdk"
+
+await apiUpload("/api/v1/resources/upload", file)
+```
+
+## Resource Hooks
+
+The SDK includes hooks for common Palette resources:
+
+- `usePluginTasks`
+- `usePluginDataRooms`
+- `usePluginChat`
+
+```tsx
+import { usePluginTasks } from "@palettelab/sdk"
+
+export function TaskList() {
+  const { tasks, loading, error, refetch } = usePluginTasks()
+
+  if (loading) return <p>Loading...</p>
+  if (error) return <p>{error}</p>
+
+  return (
+    <ul>
+      {tasks.map((task) => (
+        <li key={task.id}>{task.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Install Configuration
+
+Plugins can read and update their installation configuration through helper APIs.
+
+```ts
+import { getInstallConfig, updateInstallConfig } from "@palettelab/sdk"
+
+const config = await getInstallConfig()
+await updateInstallConfig({ ...config, enabled: true })
+```
+
+## Sandbox Bridge
+
+Appstore plugin frontends run inside an iframe sandbox by default. Use `createSandboxBridge` when you need to explicitly call host-proxied APIs from sandbox runtime code.
+
+```ts
+import { createSandboxBridge, isSandboxRuntime } from "@palettelab/sdk"
+
+if (isSandboxRuntime()) {
+  const bridge = createSandboxBridge()
+  const result = await bridge.apiFetch("/api/v1/tasks")
+  console.log(result)
+}
+```
+
+For standard React plugin templates, the runtime wiring is already handled by the platform and CLI.
+
+## Testing
+
+Use the SDK test utilities to render plugin components with a mock platform context.
+
+```tsx
+import { createMockPlatformContext, withPluginProvider } from "@palettelab/sdk"
+
+const ctx = createMockPlatformContext({
+  pluginId: "hello-sdk",
+  organizationId: 1,
+})
+
+const Wrapped = withPluginProvider(MyPluginComponent, ctx)
+```
+
+## Package Contents
+
+The npm package ships compiled CommonJS, ESM, and TypeScript declarations from `dist/`.
+
+## Related Packages
+
+- `@palettelab/cli` provides the `pltt` command for scaffolding, local dev, validation, packaging, and publishing.
+- `palette-sdk` is the Python backend SDK for FastAPI plugin routes, permissions, tools, DB helpers, RLS, and test helpers.

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-CQH23f5N.mjs';
+import { P as PlatformContext } from '../plugin-DzSTKgkz.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-CQH23f5N.js';
+import { P as PlatformContext } from '../plugin-DzSTKgkz.js';
 
 /**
  * Provider that wraps plugin components with the platform context.

package/dist/hooks/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { P as PlatformContext } from '../plugin-CQH23f5N.mjs';
+import { P as PlatformContext } from '../plugin-DzSTKgkz.mjs';
 import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, d as DataRoomFolder, c as DataRoomFile, b as ChatThread, a as ChatMessage } from '../data-room-BP0PjYoe.mjs';
 
 /**

package/dist/hooks/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { P as PlatformContext } from '../plugin-CQH23f5N.js';
+import { P as PlatformContext } from '../plugin-DzSTKgkz.js';
 import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, d as DataRoomFolder, c as DataRoomFile, b as ChatThread, a as ChatMessage } from '../data-room-BP0PjYoe.js';
 
 /**

package/dist/index.d.mts

@@ -1,9 +1,10 @@
-export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, P as PlatformContext, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from './plugin-CQH23f5N.mjs';
+import { P as PlatformContext } from './plugin-DzSTKgkz.mjs';
+export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from './plugin-DzSTKgkz.mjs';
 export { C as ChatAttachment, a as ChatMessage, b as ChatThread, D as DataRoom, c as DataRoomFile, d as DataRoomFolder, 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-BP0PjYoe.mjs';
 export { AgentResource, ResourcesByGroup } from './types/index.mjs';
+import { ReactElement } from 'react';
 export { PlatformCtx, usePlatform, usePluginChat, usePluginDataRooms, usePluginTasks } from './hooks/index.mjs';
 export { PluginProvider } from './components/index.mjs';
-import 'react';
 import 'react/jsx-runtime';
 
 /**
@@ -28,4 +29,28 @@ declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;
  */
 declare function apiUpload(path: string, file: File, fieldName?: string, extraFields?: Record<string, string>): Promise<Response>;
 
-export { apiFetch, apiUpload, getBaseUrl, setBaseUrl };
+declare class PaletteApiError extends Error {
+    status: number;
+    detail: unknown;
+    constructor(message: string, status?: number, detail?: unknown);
+}
+declare function errorFromResponse(response: Response): Promise<PaletteApiError>;
+declare function isPaletteApiError(error: unknown): error is PaletteApiError;
+
+type ToastType = "success" | "error" | "info";
+type SandboxBridge = {
+    apiFetch: PlatformContext["apiFetch"];
+    navigate: (path: string) => void;
+    showToast: (message: string, type?: ToastType) => void;
+};
+declare function createSandboxBridge(platform: Pick<PlatformContext, "apiFetch" | "navigate" | "showToast">): SandboxBridge;
+declare function isSandboxRuntime(): boolean;
+
+type InstallConfig = Record<string, unknown>;
+declare function getInstallConfig(pluginId: string): Promise<InstallConfig>;
+declare function updateInstallConfig(pluginId: string, config: InstallConfig): Promise<InstallConfig>;
+
+declare function createMockPlatformContext(overrides?: Partial<PlatformContext>): PlatformContext;
+declare function withPluginProvider(element: ReactElement, platform?: Partial<PlatformContext>): ReactElement;
+
+export { type InstallConfig, PaletteApiError, PlatformContext, type SandboxBridge, apiFetch, apiUpload, createMockPlatformContext, createSandboxBridge, errorFromResponse, getBaseUrl, getInstallConfig, isPaletteApiError, isSandboxRuntime, setBaseUrl, updateInstallConfig, withPluginProvider };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, P as PlatformContext, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from './plugin-CQH23f5N.js';
+import { P as PlatformContext } from './plugin-DzSTKgkz.js';
+export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from './plugin-DzSTKgkz.js';
 export { C as ChatAttachment, a as ChatMessage, b as ChatThread, D as DataRoom, c as DataRoomFile, d as DataRoomFolder, 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-BP0PjYoe.js';
 export { AgentResource, ResourcesByGroup } from './types/index.js';
+import { ReactElement } from 'react';
 export { PlatformCtx, usePlatform, usePluginChat, usePluginDataRooms, usePluginTasks } from './hooks/index.js';
 export { PluginProvider } from './components/index.js';
-import 'react';
 import 'react/jsx-runtime';
 
 /**
@@ -28,4 +29,28 @@ declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;
  */
 declare function apiUpload(path: string, file: File, fieldName?: string, extraFields?: Record<string, string>): Promise<Response>;
 
-export { apiFetch, apiUpload, getBaseUrl, setBaseUrl };
+declare class PaletteApiError extends Error {
+    status: number;
+    detail: unknown;
+    constructor(message: string, status?: number, detail?: unknown);
+}
+declare function errorFromResponse(response: Response): Promise<PaletteApiError>;
+declare function isPaletteApiError(error: unknown): error is PaletteApiError;
+
+type ToastType = "success" | "error" | "info";
+type SandboxBridge = {
+    apiFetch: PlatformContext["apiFetch"];
+    navigate: (path: string) => void;
+    showToast: (message: string, type?: ToastType) => void;
+};
+declare function createSandboxBridge(platform: Pick<PlatformContext, "apiFetch" | "navigate" | "showToast">): SandboxBridge;
+declare function isSandboxRuntime(): boolean;
+
+type InstallConfig = Record<string, unknown>;
+declare function getInstallConfig(pluginId: string): Promise<InstallConfig>;
+declare function updateInstallConfig(pluginId: string, config: InstallConfig): Promise<InstallConfig>;
+
+declare function createMockPlatformContext(overrides?: Partial<PlatformContext>): PlatformContext;
+declare function withPluginProvider(element: ReactElement, platform?: Partial<PlatformContext>): ReactElement;
+
+export { type InstallConfig, PaletteApiError, PlatformContext, type SandboxBridge, apiFetch, apiUpload, createMockPlatformContext, createSandboxBridge, errorFromResponse, getBaseUrl, getInstallConfig, isPaletteApiError, isSandboxRuntime, setBaseUrl, updateInstallConfig, withPluginProvider };

package/dist/index.js

@@ -20,16 +20,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  PaletteApiError: () => PaletteApiError,
   PlatformCtx: () => PlatformCtx,
   PluginProvider: () => PluginProvider,
   apiFetch: () => apiFetch,
   apiUpload: () => apiUpload,
+  createMockPlatformContext: () => createMockPlatformContext,
+  createSandboxBridge: () => createSandboxBridge,
+  errorFromResponse: () => errorFromResponse,
   getBaseUrl: () => getBaseUrl,
+  getInstallConfig: () => getInstallConfig,
+  isPaletteApiError: () => isPaletteApiError,
+  isSandboxRuntime: () => isSandboxRuntime,
   setBaseUrl: () => setBaseUrl,
+  updateInstallConfig: () => updateInstallConfig,
   usePlatform: () => usePlatform,
   usePluginChat: () => usePluginChat,
   usePluginDataRooms: () => usePluginDataRooms,
-  usePluginTasks: () => usePluginTasks
+  usePluginTasks: () => usePluginTasks,
+  withPluginProvider: () => withPluginProvider
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -92,6 +101,53 @@ async function apiUpload(path, file, fieldName = "file", extraFields) {
   return res;
 }
 
+// src/errors.ts
+var PaletteApiError = class extends Error {
+  constructor(message, status = 0, detail) {
+    super(message);
+    this.name = "PaletteApiError";
+    this.status = status;
+    this.detail = detail;
+  }
+};
+async function errorFromResponse(response) {
+  const body = await response.json().catch(() => null);
+  const message = body && typeof body === "object" && "detail" in body ? String(body.detail) : response.statusText;
+  return new PaletteApiError(message, response.status, body);
+}
+function isPaletteApiError(error) {
+  return error instanceof PaletteApiError;
+}
+
+// src/sandbox-bridge.ts
+function createSandboxBridge(platform) {
+  return {
+    apiFetch: platform.apiFetch,
+    navigate: platform.navigate,
+    showToast: platform.showToast
+  };
+}
+function isSandboxRuntime() {
+  if (typeof window === "undefined") return false;
+  return Boolean(window.__palettePluginHost);
+}
+
+// src/install-config.ts
+async function getInstallConfig(pluginId) {
+  const res = await apiFetch(`/api/v1/app-installs/${encodeURIComponent(pluginId)}/config`);
+  return res.json();
+}
+async function updateInstallConfig(pluginId, config) {
+  const res = await apiFetch(`/api/v1/app-installs/${encodeURIComponent(pluginId)}/config`, {
+    method: "PATCH",
+    body: JSON.stringify({ values: config })
+  });
+  return res.json();
+}
+
+// src/test-utils.tsx
+var import_react2 = require("react");
+
 // src/hooks/use-platform.ts
 var import_react = require("react");
 var PlatformCtx = (0, import_react.createContext)(null);
@@ -105,14 +161,65 @@ function usePlatform() {
   return ctx;
 }
 
+// src/components/plugin-provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function PluginProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PlatformCtx.Provider, { value, children });
+}
+
+// src/test-utils.tsx
+var mockUser = {
+  id: "test-user",
+  email: "test@example.com",
+  name: "Test User",
+  is_active: true,
+  created_at: (/* @__PURE__ */ new Date(0)).toISOString(),
+  onboarding_completed: true,
+  company_name: null,
+  company_type: null,
+  org_theme: null,
+  org_logo: null,
+  org_enabled_menu_items: null,
+  org_menu_labels: null,
+  org_enabled_apps: null,
+  org_app_store_enabled: true,
+  org_enabled_agent_ids: null,
+  organization_id: 1,
+  org_role: "owner"
+};
+function createMockPlatformContext(overrides = {}) {
+  return {
+    user: mockUser,
+    organizationId: 1,
+    orgRole: "owner",
+    orgs: [],
+    agents: [],
+    apiFetch: async () => new Response(JSON.stringify({}), { status: 200 }),
+    navigate: () => {
+    },
+    showToast: () => {
+    },
+    ...overrides
+  };
+}
+function withPluginProvider(element, platform = {}) {
+  return (0, import_react2.createElement)(
+    PluginProvider,
+    { value: createMockPlatformContext(platform), children: element }
+  );
+}
+
 // src/hooks/use-plugin-tasks.ts
-var import_react2 = require("react");
+var import_react3 = require("react");
 function usePluginTasks(agentId) {
   const { apiFetch: apiFetch2 } = usePlatform();
-  const [tasks, setTasks] = (0, import_react2.useState)([]);
-  const [stats, setStats] = (0, import_react2.useState)(null);
-  const [loading, setLoading] = (0, import_react2.useState)(true);
-  const fetchTasks = (0, import_react2.useCallback)(async () => {
+  const [tasks, setTasks] = (0, import_react3.useState)([]);
+  const [stats, setStats] = (0, import_react3.useState)(null);
+  const [loading, setLoading] = (0, import_react3.useState)(true);
+  const fetchTasks = (0, import_react3.useCallback)(async () => {
     try {
       const params = new URLSearchParams();
       if (agentId) params.set("agent_id", String(agentId));
@@ -121,18 +228,18 @@ function usePluginTasks(agentId) {
     } catch {
     }
   }, [apiFetch2, agentId]);
-  const fetchStats = (0, import_react2.useCallback)(async () => {
+  const fetchStats = (0, import_react3.useCallback)(async () => {
     try {
       const res = await apiFetch2("/api/v1/tasks/stats");
       setStats(await res.json());
     } catch {
     }
   }, [apiFetch2]);
-  (0, import_react2.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     setLoading(true);
     Promise.all([fetchTasks(), fetchStats()]).finally(() => setLoading(false));
   }, [fetchTasks, fetchStats]);
-  const createTask = (0, import_react2.useCallback)(async (payload) => {
+  const createTask = (0, import_react3.useCallback)(async (payload) => {
     const res = await apiFetch2("/api/v1/tasks", {
       method: "POST",
       body: JSON.stringify(payload)
@@ -141,7 +248,7 @@ function usePluginTasks(agentId) {
     await Promise.all([fetchTasks(), fetchStats()]);
     return task;
   }, [apiFetch2, fetchTasks, fetchStats]);
-  const updateTask = (0, import_react2.useCallback)(async (taskId, payload) => {
+  const updateTask = (0, import_react3.useCallback)(async (taskId, payload) => {
     const res = await apiFetch2(`/api/v1/tasks/${taskId}`, {
       method: "PATCH",
       body: JSON.stringify(payload)
@@ -150,7 +257,7 @@ function usePluginTasks(agentId) {
     await Promise.all([fetchTasks(), fetchStats()]);
     return task;
   }, [apiFetch2, fetchTasks, fetchStats]);
-  const deleteTask = (0, import_react2.useCallback)(async (taskId) => {
+  const deleteTask = (0, import_react3.useCallback)(async (taskId) => {
     await apiFetch2(`/api/v1/tasks/${taskId}`, { method: "DELETE" });
     await Promise.all([fetchTasks(), fetchStats()]);
   }, [apiFetch2, fetchTasks, fetchStats]);
@@ -158,23 +265,23 @@ function usePluginTasks(agentId) {
 }
 
 // src/hooks/use-plugin-data-rooms.ts
-var import_react3 = require("react");
+var import_react4 = require("react");
 function usePluginDataRooms() {
   const { apiFetch: apiFetch2 } = usePlatform();
-  const [rooms, setRooms] = (0, import_react3.useState)([]);
-  const [loading, setLoading] = (0, import_react3.useState)(true);
-  const fetchRooms = (0, import_react3.useCallback)(async () => {
+  const [rooms, setRooms] = (0, import_react4.useState)([]);
+  const [loading, setLoading] = (0, import_react4.useState)(true);
+  const fetchRooms = (0, import_react4.useCallback)(async () => {
     try {
       const res = await apiFetch2("/api/v1/data-rooms");
       setRooms(await res.json());
     } catch {
     }
   }, [apiFetch2]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react4.useEffect)(() => {
     setLoading(true);
     fetchRooms().finally(() => setLoading(false));
   }, [fetchRooms]);
-  const fetchFolder = (0, import_react3.useCallback)(async (roomId, folderId) => {
+  const fetchFolder = (0, import_react4.useCallback)(async (roomId, folderId) => {
     const path = folderId ? `/api/v1/data-rooms/${roomId}/folders/${folderId}` : `/api/v1/data-rooms/${roomId}`;
     const res = await apiFetch2(path);
     return res.json();
@@ -183,19 +290,19 @@ function usePluginDataRooms() {
 }
 
 // src/hooks/use-plugin-chat.ts
-var import_react4 = require("react");
+var import_react5 = require("react");
 function usePluginChat(agentId) {
   const { apiFetch: apiFetch2 } = usePlatform();
-  const [threads, setThreads] = (0, import_react4.useState)([]);
-  const [messages, setMessages] = (0, import_react4.useState)([]);
-  const [streaming, setStreaming] = (0, import_react4.useState)(false);
-  const [activeThreadId, setActiveThreadId] = (0, import_react4.useState)(null);
-  const abortRef = (0, import_react4.useRef)(null);
-  const fetchThreads = (0, import_react4.useCallback)(async () => {
+  const [threads, setThreads] = (0, import_react5.useState)([]);
+  const [messages, setMessages] = (0, import_react5.useState)([]);
+  const [streaming, setStreaming] = (0, import_react5.useState)(false);
+  const [activeThreadId, setActiveThreadId] = (0, import_react5.useState)(null);
+  const abortRef = (0, import_react5.useRef)(null);
+  const fetchThreads = (0, import_react5.useCallback)(async () => {
     const res = await apiFetch2(`/api/v1/chat/${agentId}/threads`);
     setThreads(await res.json());
   }, [apiFetch2, agentId]);
-  const createThread = (0, import_react4.useCallback)(async () => {
+  const createThread = (0, import_react5.useCallback)(async () => {
     const res = await apiFetch2(`/api/v1/chat/${agentId}/threads`, { method: "POST" });
     const thread = await res.json();
     setActiveThreadId(thread.id);
@@ -203,13 +310,13 @@ function usePluginChat(agentId) {
     await fetchThreads();
     return thread;
   }, [apiFetch2, agentId, fetchThreads]);
-  const fetchMessages = (0, import_react4.useCallback)(async (threadId) => {
+  const fetchMessages = (0, import_react5.useCallback)(async (threadId) => {
     const res = await apiFetch2(`/api/v1/chat/threads/${threadId}/messages`);
     const msgs = await res.json();
     setMessages(msgs);
     setActiveThreadId(threadId);
   }, [apiFetch2]);
-  const sendMessage = (0, import_react4.useCallback)(async (threadId, content) => {
+  const sendMessage = (0, import_react5.useCallback)(async (threadId, content) => {
     setStreaming(true);
     abortRef.current = new AbortController();
     const userMsg = {
@@ -277,7 +384,7 @@ function usePluginChat(agentId) {
       abortRef.current = null;
     }
   }, []);
-  const stopStreaming = (0, import_react4.useCallback)(() => {
+  const stopStreaming = (0, import_react5.useCallback)(() => {
     abortRef.current?.abort();
   }, []);
   return {
@@ -292,25 +399,25 @@ function usePluginChat(agentId) {
     stopStreaming
   };
 }
-
-// src/components/plugin-provider.tsx
-var import_jsx_runtime = require("react/jsx-runtime");
-function PluginProvider({
-  value,
-  children
-}) {
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PlatformCtx.Provider, { value, children });
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PaletteApiError,
   PlatformCtx,
   PluginProvider,
   apiFetch,
   apiUpload,
+  createMockPlatformContext,
+  createSandboxBridge,
+  errorFromResponse,
   getBaseUrl,
+  getInstallConfig,
+  isPaletteApiError,
+  isSandboxRuntime,
   setBaseUrl,
+  updateInstallConfig,
   usePlatform,
   usePluginChat,
   usePluginDataRooms,
-  usePluginTasks
+  usePluginTasks,
+  withPluginProvider
 });

package/dist/index.mjs

@@ -57,6 +57,53 @@ async function apiUpload(path, file, fieldName = "file", extraFields) {
   return res;
 }
 
+// src/errors.ts
+var PaletteApiError = class extends Error {
+  constructor(message, status = 0, detail) {
+    super(message);
+    this.name = "PaletteApiError";
+    this.status = status;
+    this.detail = detail;
+  }
+};
+async function errorFromResponse(response) {
+  const body = await response.json().catch(() => null);
+  const message = body && typeof body === "object" && "detail" in body ? String(body.detail) : response.statusText;
+  return new PaletteApiError(message, response.status, body);
+}
+function isPaletteApiError(error) {
+  return error instanceof PaletteApiError;
+}
+
+// src/sandbox-bridge.ts
+function createSandboxBridge(platform) {
+  return {
+    apiFetch: platform.apiFetch,
+    navigate: platform.navigate,
+    showToast: platform.showToast
+  };
+}
+function isSandboxRuntime() {
+  if (typeof window === "undefined") return false;
+  return Boolean(window.__palettePluginHost);
+}
+
+// src/install-config.ts
+async function getInstallConfig(pluginId) {
+  const res = await apiFetch(`/api/v1/app-installs/${encodeURIComponent(pluginId)}/config`);
+  return res.json();
+}
+async function updateInstallConfig(pluginId, config) {
+  const res = await apiFetch(`/api/v1/app-installs/${encodeURIComponent(pluginId)}/config`, {
+    method: "PATCH",
+    body: JSON.stringify({ values: config })
+  });
+  return res.json();
+}
+
+// src/test-utils.tsx
+import { createElement } from "react";
+
 // src/hooks/use-platform.ts
 import { createContext, useContext } from "react";
 var PlatformCtx = createContext(null);
@@ -70,6 +117,57 @@ function usePlatform() {
   return ctx;
 }
 
+// src/components/plugin-provider.tsx
+import { jsx } from "react/jsx-runtime";
+function PluginProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(PlatformCtx.Provider, { value, children });
+}
+
+// src/test-utils.tsx
+var mockUser = {
+  id: "test-user",
+  email: "test@example.com",
+  name: "Test User",
+  is_active: true,
+  created_at: (/* @__PURE__ */ new Date(0)).toISOString(),
+  onboarding_completed: true,
+  company_name: null,
+  company_type: null,
+  org_theme: null,
+  org_logo: null,
+  org_enabled_menu_items: null,
+  org_menu_labels: null,
+  org_enabled_apps: null,
+  org_app_store_enabled: true,
+  org_enabled_agent_ids: null,
+  organization_id: 1,
+  org_role: "owner"
+};
+function createMockPlatformContext(overrides = {}) {
+  return {
+    user: mockUser,
+    organizationId: 1,
+    orgRole: "owner",
+    orgs: [],
+    agents: [],
+    apiFetch: async () => new Response(JSON.stringify({}), { status: 200 }),
+    navigate: () => {
+    },
+    showToast: () => {
+    },
+    ...overrides
+  };
+}
+function withPluginProvider(element, platform = {}) {
+  return createElement(
+    PluginProvider,
+    { value: createMockPlatformContext(platform), children: element }
+  );
+}
+
 // src/hooks/use-plugin-tasks.ts
 import { useCallback, useEffect, useState } from "react";
 function usePluginTasks(agentId) {
@@ -257,24 +355,24 @@ function usePluginChat(agentId) {
     stopStreaming
   };
 }
-
-// src/components/plugin-provider.tsx
-import { jsx } from "react/jsx-runtime";
-function PluginProvider({
-  value,
-  children
-}) {
-  return /* @__PURE__ */ jsx(PlatformCtx.Provider, { value, children });
-}
 export {
+  PaletteApiError,
   PlatformCtx,
   PluginProvider,
   apiFetch,
   apiUpload,
+  createMockPlatformContext,
+  createSandboxBridge,
+  errorFromResponse,
   getBaseUrl,
+  getInstallConfig,
+  isPaletteApiError,
+  isSandboxRuntime,
   setBaseUrl,
+  updateInstallConfig,
   usePlatform,
   usePluginChat,
   usePluginDataRooms,
-  usePluginTasks
+  usePluginTasks,
+  withPluginProvider
 };

package/dist/{plugin-CQH23f5N.d.mts → plugin-DzSTKgkz.d.mts}

@@ -71,6 +71,7 @@ interface AgentConfig {
 type AppCategory = "All" | "Productivity" | "Design" | "Marketing" | "Analytics";
 /** Plugin manifest — corresponds to palette-plugin.json */
 interface PluginManifest {
+    manifest_version: "1";
     id: string;
     name: string;
     version: string;
@@ -83,8 +84,26 @@ interface PluginManifest {
         bg: string;
         text: string;
     };
+    sdk?: {
+        frontend?: string;
+        backend?: string;
+    };
+    platform?: {
+        min_version?: string;
+        max_version?: string;
+    };
+    capabilities?: {
+        frontend?: boolean;
+        backend?: boolean;
+        database?: boolean;
+        webhooks?: boolean;
+        scheduled_jobs?: boolean;
+        file_uploads?: boolean;
+        external_network?: string[];
+    };
     frontend?: {
         entry: string;
+        sandbox?: boolean;
     };
     backend?: {
         entry: string;
@@ -93,6 +112,10 @@ interface PluginManifest {
     agents?: PluginAgentDefinition[];
     tools?: PluginToolDefinition[];
     permissions?: string[];
+    public_routes?: string[];
+    rate_limit?: {
+        per_minute?: number;
+    };
     rating?: number;
     reviews?: number;
     featured?: boolean;

package/dist/{plugin-CQH23f5N.d.ts → plugin-DzSTKgkz.d.ts}

@@ -71,6 +71,7 @@ interface AgentConfig {
 type AppCategory = "All" | "Productivity" | "Design" | "Marketing" | "Analytics";
 /** Plugin manifest — corresponds to palette-plugin.json */
 interface PluginManifest {
+    manifest_version: "1";
     id: string;
     name: string;
     version: string;
@@ -83,8 +84,26 @@ interface PluginManifest {
         bg: string;
         text: string;
     };
+    sdk?: {
+        frontend?: string;
+        backend?: string;
+    };
+    platform?: {
+        min_version?: string;
+        max_version?: string;
+    };
+    capabilities?: {
+        frontend?: boolean;
+        backend?: boolean;
+        database?: boolean;
+        webhooks?: boolean;
+        scheduled_jobs?: boolean;
+        file_uploads?: boolean;
+        external_network?: string[];
+    };
     frontend?: {
         entry: string;
+        sandbox?: boolean;
     };
     backend?: {
         entry: string;
@@ -93,6 +112,10 @@ interface PluginManifest {
     agents?: PluginAgentDefinition[];
     tools?: PluginToolDefinition[];
     permissions?: string[];
+    public_routes?: string[];
+    rate_limit?: {
+        per_minute?: number;
+    };
     rating?: number;
     reviews?: number;
     featured?: boolean;

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, P as PlatformContext, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from '../plugin-CQH23f5N.mjs';
+export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, P as PlatformContext, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from '../plugin-DzSTKgkz.mjs';
 export { C as ChatAttachment, a as ChatMessage, b as ChatThread, D as DataRoom, c as DataRoomFile, d as DataRoomFolder, 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-BP0PjYoe.mjs';
 
 interface AgentResource {

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, P as PlatformContext, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from '../plugin-CQH23f5N.js';
+export { A as Agent, a as AgentConfig, b as AppCategory, c as AuthContextValue, O as OrgSummary, P as PlatformContext, d as PluginAgentDefinition, e as PluginComponentProps, f as PluginManifest, g as PluginToolDefinition, U as User } from '../plugin-DzSTKgkz.js';
 export { C as ChatAttachment, a as ChatMessage, b as ChatThread, D as DataRoom, c as DataRoomFile, d as DataRoomFolder, 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-BP0PjYoe.js';
 
 interface AgentResource {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Palette Platform SDK for building plugins and apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,16 +27,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "registry": "https://npm.pkg.github.com"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/palette-lab/virtual-organisation.git",
+    "url": "git+https://github.com/palette-lab/virtual-organisation.git",
     "directory": "sdk/frontend"
   },
   "scripts": {