@palettelab/sdk 0.1.1 → 0.1.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Palette Platform SDK for building plugins and apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,15 +27,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com"
+    "registry": "https://registry.npmjs.org"
   },
   "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": {