@palettelab/cli 0.3.56 → 0.3.58

package/README.md

@@ -4,6 +4,20 @@ Developer CLI for building plugins for the Palette platform. Works without any a
 
 The installed executable is `pltt`.
 
+## API Surface Split
+
+Use the right helper for the runtime you are coding in:
+
+| Runtime | Package/helper | Use it for |
+|---|---|---|
+| Frontend TypeScript/React | `@palettelab/sdk`, `createPaletteClient(...)`, `palette.*` | UI code, current-user OS APIs, frontend broker clients, Data Room browsing/upload from the browser, toasts, and current-user OS notifications |
+| Backend Python/FastAPI | `palette_sdk`, `PluginContext`, `ctx.*`, `services(ctx)` | Backend routes, permission gates, app-owned data, migrations, cross-user notifications, server-side Data Rooms, managed services, app-to-app service handlers, and lifecycle hooks |
+| CLI tooling | `pltt ...` | Scaffolding, local dev, testing, packaging, publishing, hosted sandbox previews, and generating frontend/backend typed service clients |
+
+The CLI bundles `palette_sdk` for local backend simulation, but backend app
+code should import `palette_sdk`, not `@palettelab/sdk`. Frontend app code
+should import `@palettelab/sdk`, not `palette_sdk`.
+
 ## Requirements
 
 - Node.js 18+
@@ -337,7 +351,12 @@ async def sync_invoices(ctx: PluginContext = Depends(get_plugin_context)):
 
 Storage upload responses include both snake_case and camelCase aliases for object metadata (`object_path`/`objectPath`, `file_url`/`fileUrl`, `content_type`/`contentType`) so local simulator and hosted OS responses can be consumed with the same app code.
 
-App storage is different from Data Room uploads. Use `ctx.storage` or `palette.storage` for app-owned files written directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` / `palette.dataRooms` only when the file should be managed as a Data Room document.
+App storage is different from Data Room uploads. Backend Python code uses
+`ctx.storage`; frontend TypeScript code uses `palette.storage`. Both write
+app-owned files directly to the OS-configured storage backend, currently GCS in
+hosted environments. Use backend `ctx.data_rooms` or frontend
+`palette.dataRooms` only when the file should be managed as a Data Room
+document.
 
 Python backend app-storage example:
 
@@ -398,28 +417,10 @@ package dependency policy, and backend package size.
 
 ## OS Notifications
 
-Apps can push persistent notifications into the Palette OS notification center
-(the bell) with `@palettelab/sdk@0.1.27+`:
-
-```ts
-import { notifications } from "@palettelab/sdk"
-// or: palette.notifications.push(...)
-
-await notifications.push({
-  title: "Export complete",
-  body: "Your report is ready to download.",
-  severity: "success",          // "info" | "success" | "warning" | "error"
-  targetApp: "reports-app",     // app icon that owns the unread badge
-  route: "/exports/123",        // opened inside your app on click
-})
-```
-
-The notification shows as a live toast plus a notification-center entry;
-clicking it opens/focuses the target app at the resolved route. Use the SDK
-helper rather than hand-building platform notification API calls.
-
-Python plugin backends can push too, via `ctx.notifications` in the CLI-bundled
-backend SDK:
+Backend apps created or served by the CLI should use the Python helper from the
+CLI-bundled backend SDK. This is the helper to use for cross-user flows such as
+leave approvals, review requests, task assignment, and same-organisation
+recipient targeting:
 
 ```python
 from palette_sdk import PluginContext, get_plugin_context, require_permission
@@ -432,14 +433,39 @@ async def start_export(ctx: PluginContext = Depends(get_plugin_context)):
         body="A leave request needs approval.",
         to=ctx.notifications.user(approver_user_id),
         target_app="hierarchy-app",
+        route=f"/approvals/{request_id}",
+        severity="warning",            # "info" | "success" | "warning" | "error"
+        data={"request_id": request_id},
     )
 ```
 
 By default the backend helper notifies the user making the current request;
 pass `to=ctx.notifications.user(...)`, `.email(...)`, `.member(...)`,
 `.role(...)`, `.team(...)`, or `.mentions_from(...)` to notify other same-org
-members. `target_app` controls the app icon badge and default click target. See
-`docs/python-backend-sdk.md` ("OS Notifications From Python") for details.
+members. `target_app` controls the app icon badge and default click target.
+`route` is optional and should only be set when the target app has a matching
+deep-link page. See `docs/python-backend-sdk.md` ("OS Notifications From
+Python") for details.
+
+Frontend apps can also push notifications for the current signed-in user with
+`@palettelab/sdk@0.1.27+`. This TypeScript helper is frontend-only and is not
+the Python backend helper:
+
+```ts
+import { notifications } from "@palettelab/sdk"
+// or: palette.notifications.push(...)
+
+await notifications.push({
+  title: "Export complete",
+  body: "Your report is ready to download.",
+  severity: "success",          // "info" | "success" | "warning" | "error"
+  targetApp: "reports-app",     // app icon that owns the unread badge
+  route: "/exports/123",        // opened inside your app on click
+})
+```
+
+Both helpers create a live toast plus a notification-center entry. Use these
+helpers rather than hand-building platform notification API calls.
 
 During `pltt dev`, frontend pushes call the platform backend directly
 (`NEXT_PUBLIC_API_URL`, default `http://localhost:8000`) in the user's session,

package/docs/python-backend-sdk.md

@@ -881,7 +881,12 @@ Example mock:
 }
 ```
 
-App storage is separate from Data Rooms. Use `ctx.storage` and `palette.storage` for app-owned files that go directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` or `palette.dataRooms` only when the file should be visible and governed as a Data Room document.
+App storage is separate from Data Rooms. Backend Python code uses
+`ctx.storage`; frontend TypeScript code uses `palette.storage`. Both write
+app-owned files directly to the OS-configured storage backend, currently GCS in
+hosted environments. Use backend `ctx.data_rooms` or frontend
+`palette.dataRooms` only when the file should be visible and governed as a Data
+Room document.
 
 Palette scopes storage the same way. Files written through `ctx.storage` or the
 frontend storage client live under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.56",
+  "version": "0.3.58",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"