@palettelab/cli 0.3.54 → 0.3.55

package/README.md

@@ -396,6 +396,56 @@ The CLI validates manifest shape, SDK compatibility, frontend bundling, backend
 imports, backend route permission gates, declared permissions, migration safety,
 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.25+`:
+
+```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"
+  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 your app window at the resolved route. The stable
+contract is `POST /api/v1/notifications/` on the platform API (delivery streams
+over `GET /api/v1/notifications/stream`, SSE).
+
+Python plugin backends can push too, via `ctx.notifications` (palette-sdk
+`0.1.9+`):
+
+```python
+from palette_sdk import PluginContext, get_plugin_context, require_permission
+
+@router.post("/exports", dependencies=[require_permission("resources:write")])
+async def start_export(ctx: PluginContext = Depends(get_plugin_context)):
+    ...
+    await ctx.notifications.push(
+        "Export complete",
+        body="Your report is ready to download.",
+        severity="success",
+        route="/exports/123",
+    )
+```
+
+By default the backend helper notifies the user making the current request;
+pass `user_id` to notify another member of the same organisation. See
+`docs/python-backend-sdk.md` ("OS Notifications From Python") for details.
+
+During `pltt dev`, frontend pushes call the platform backend directly
+(`NEXT_PUBLIC_API_URL`, default `http://localhost:8000`) in the user's session,
+so they land in the real notification pool. Backend pushes run against the
+local simulator, which logs them as `[palette-notification] {...}` and returns
+a stub. Sandboxed iframe apps are not supported yet (no session cookie inside
+the iframe).
+
 ## Commands
 
 ### `pltt init <name>`

package/backend-sdk/palette_sdk/__init__.py

@@ -6,6 +6,7 @@ from palette_sdk.data_rooms import DataRoomsClient
 from palette_sdk.connections import ConnectionStatus, MissingConnectionError, PluginConnectionsClient
 from palette_sdk.apps import AppInteropClient, AppServiceClient, MissingAppServiceError
 from palette_sdk.members import OrganizationMembersClient
+from palette_sdk.notifications import NotificationsClient
 from palette_sdk.platform_services import (
     LocalRedisService,
     LocalVectorService,
@@ -62,6 +63,7 @@ __all__ = [
     "AppServiceClient",
     "MissingAppServiceError",
     "OrganizationMembersClient",
+    "NotificationsClient",
     "LocalRedisService",
     "LocalVectorService",
     "PlatformServiceUnavailable",

package/backend-sdk/palette_sdk/notifications.py

@@ -0,0 +1,67 @@
+"""Backend OS notification helpers for plugin Python code.
+
+Push a persistent notification into the OS notification center from a plugin
+backend — the Python counterpart of the frontend SDK's `notifications.push()`:
+
+    from palette_sdk import PluginContext, get_plugin_context
+
+    @router.post("/exports", dependencies=[require_permission("resources:write")])
+    async def start_export(ctx: PluginContext = Depends(get_plugin_context)):
+        ...
+        await ctx.notifications.push(
+            "Export complete",
+            body="Your report is ready to download.",
+            severity="success",
+            route="/exports/123",
+        )
+
+`route` resolves relative to the calling app (`/apps/{plugin_id}/exports/123`);
+pass an absolute `/apps/...` route to target another app's window. By default
+the notification goes to the user making the current request; pass `user_id`
+to notify a different member of the same organisation (the platform rejects
+targets outside the caller's org).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class NotificationsClient:
+    """Thin wrapper around the platform-injected notification service.
+
+    In production/hosted sandbox the platform injects the service into
+    `PluginContext`. In local unit tests, pass a fake service with the same
+    async `push` method.
+    """
+
+    def __init__(self, service: Any = None):
+        self._service = service
+
+    def _require_service(self) -> Any:
+        if self._service is None:
+            raise RuntimeError(
+                "Notification service is not available in this runtime. "
+                "Run inside Palette OS/hosted sandbox or inject a fake service in tests."
+            )
+        return self._service
+
+    async def push(
+        self,
+        title: str,
+        *,
+        body: str | None = None,
+        route: str | None = None,
+        severity: str | None = None,
+        data: dict[str, Any] | None = None,
+        user_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Push a notification; returns the serialized notification dict."""
+        return await self._require_service().push(
+            title=title,
+            body=body,
+            route=route,
+            severity=severity,
+            data=data,
+            user_id=user_id,
+        )

package/backend-sdk/palette_sdk/plugin_context.py

@@ -14,6 +14,7 @@ from palette_sdk.data_rooms import DataRoomsClient
 from palette_sdk.connections import PluginConnectionsClient
 from palette_sdk.apps import AppInteropClient
 from palette_sdk.members import OrganizationMembersClient
+from palette_sdk.notifications import NotificationsClient
 from palette_sdk.platform_services import UnavailablePlatformService
 from palette_sdk.events import EventPublisher
 
@@ -40,6 +41,7 @@ class PluginContext:
         permissions: List of permissions declared in the manifest
         storage: Storage service for file upload/download
         members: Organization member helpers for the current org
+        notifications: OS notification center push helpers
     """
     db: AsyncSession
     user_id: str
@@ -52,6 +54,7 @@ class PluginContext:
     connections: PluginConnectionsClient = field(default_factory=PluginConnectionsClient)
     apps: AppInteropClient = field(default_factory=AppInteropClient)
     members: OrganizationMembersClient = field(default_factory=OrganizationMembersClient)
+    notifications: NotificationsClient = field(default_factory=NotificationsClient)
     redis: Any = field(default_factory=lambda: UnavailablePlatformService("redis"))
     vector: Any = field(default_factory=lambda: UnavailablePlatformService("vector"))
     events: EventPublisher = field(default_factory=EventPublisher)
@@ -128,6 +131,7 @@ async def get_plugin_context(request: Request) -> PluginContext:
             getattr(state, "org_members", None),
             getattr(state, "plugin_permissions", []),
         ),
+        notifications=NotificationsClient(getattr(state, "notifications", None)),
         redis=getattr(state, "redis", None) or UnavailablePlatformService("redis"),
         vector=getattr(state, "vector", None) or UnavailablePlatformService("vector"),
         events=EventPublisher(getattr(state, "plugin_events", None)),

package/backend-sdk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "palette-sdk"
-version = "0.1.8"
+version = "0.1.9"
 description = "Palette Platform SDK for building backend plugins"
 readme = "README.md"
 requires-python = ">=3.12"

package/docs/python-backend-sdk.md

@@ -114,6 +114,7 @@ Available context values:
 | `ctx.data_rooms` | Backend Data Room client |
 | `ctx.connections` | Palette-managed third-party connection client |
 | `ctx.members` | Current organisation member client |
+| `ctx.notifications` | Push OS notification-center notifications |
 | `ctx.apps` / `services(ctx)` | Governed app-to-app calls through declared `consumes` contracts |
 | `ctx.events` | Publish event topics declared in `provides.events` |
 | `ctx.redis` | Plugin/org-scoped Redis-style service when `platform_services` includes `redis` |
@@ -141,6 +142,7 @@ These are the public Python helpers exported by `palette_sdk`.
 | `KNOWN_PERMISSIONS`, `is_known_permission(...)` | Permission vocabulary checks for manifests/tools |
 | `DataRoomsClient`, `ctx.data_rooms` | Backend Data Room room/folder/file helpers |
 | `OrganizationMembersClient`, `ctx.members` | Current-organization member lookup, invite, and role helpers |
+| `NotificationsClient`, `ctx.notifications` | Push notifications into the OS notification center |
 | `PluginConnectionsClient`, `ConnectionStatus`, `MissingConnectionError`, `ctx.connections` | Third-party connection status and token helpers |
 | `AppInteropClient`, `AppServiceClient`, `MissingAppServiceError`, `ctx.apps` | Call required apps/services without direct database access |
 | `service(...)`, `services(ctx)`, `ServicesClient`, `BrokerCallError` | Provide and consume OS-broker service methods/events |
@@ -592,6 +594,50 @@ In local unit tests outside the Palette runtime, inject a fake Data Room service
 if you need to test routes that call `ctx.data_rooms`. In hosted sandbox and
 real OS runtime, the platform injects the real service.
 
+## 8a. OS Notifications From Python
+
+Backend code can push persistent notifications into the OS notification
+center (the bell) — the Python counterpart of the frontend SDK's
+`notifications.push()`:
+
+```python
+from palette_sdk import PluginContext, get_plugin_context, require_permission
+
+@router.post("/exports", dependencies=[require_permission("resources:write")])
+async def start_export(ctx: PluginContext = Depends(get_plugin_context)):
+    ...
+    await ctx.notifications.push(
+        "Export complete",
+        body="Your report is ready to download.",
+        severity="success",            # "info" | "success" | "warning" | "error"
+        route="/exports/123",          # opened inside your app on click
+        data={"export_id": 123},       # arbitrary payload stored with it
+    )
+```
+
+The notification shows as a live toast plus a notification-center entry and
+opens/focuses your app window at the resolved route when clicked. `route`
+resolves relative to your app (`/apps/{plugin_id}/exports/123`); pass an
+absolute `/apps/...` route to target another app's window. Omit `route` to
+open your app's main window.
+
+By default the notification targets the user making the current request. Pass
+`user_id` to notify a different member of the same organisation (useful for
+approval flows); targets outside the caller's organisation are rejected:
+
+```python
+await ctx.notifications.push(
+    "Approval needed",
+    body=f"{requester.name} requested a budget increase.",
+    route="/approvals",
+    user_id=str(approver_id),
+)
+```
+
+During `pltt dev` notifications are not delivered to a real notification
+center — the simulator logs them as `[palette-notification] {...}` and returns
+a stub response, so your code paths still run.
+
 ## 9. Config And Secrets
 
 Use config for app install settings and secrets for sensitive values.

package/lib/commands/publish.js

@@ -410,6 +410,7 @@ async function run(argv, { cwd }) {
   log(`[pltt]     ${backend.length} bytes`)
 
   const backendSha = sha256(backend)
+  const frontendSha = frontend ? sha256(frontend) : null
   const api = makeApi(env)
 
   log("[pltt]   requesting signed URLs")
@@ -419,6 +420,7 @@ async function run(argv, { cwd }) {
       plugin_id: manifest.id,
       version: manifest.version,
       bundle_sha256: backendSha,
+      ...(frontendSha ? { frontend_sha256: frontendSha } : {}),
       publish_type: publishType,
     },
   })

package/lib/dev-simulator.js

@@ -178,6 +178,7 @@ import pathlib
 import re
 import sys
 import uuid
+from datetime import datetime, timezone
 from types import SimpleNamespace
 
 from fastapi import FastAPI, HTTPException, Request, Response
@@ -301,6 +302,47 @@ class LocalEventPublisher:
     async def publish(self, topic: str, payload=None):
         print("[palette-event]", topic, json.dumps(payload or {}, sort_keys=True))
 
+class LocalNotificationsService:
+    """Local stand-in for the platform notification pool: logs and returns a stub."""
+
+    def __init__(self):
+        self._next_id = 1
+
+    def _resolve_action_route(self, route, plugin_id):
+        if not route:
+            return f"/apps/{plugin_id}" if plugin_id else None
+        if "://" in route:
+            raise ValueError("route must be an internal route starting with '/'")
+        if route.startswith("/apps/"):
+            return route
+        suffix = route if route.startswith("/") else "/" + route
+        return f"/apps/{plugin_id}{suffix}" if plugin_id else suffix
+
+    async def push(self, *, title, body=None, route=None, severity=None, data=None, user_id=None):
+        if not title or not str(title).strip():
+            raise ValueError("notification title is required")
+        if severity is not None and severity not in ("info", "success", "warning", "error"):
+            raise ValueError("severity must be one of: info, success, warning, error")
+        plugin_id = MANIFEST.get("id", "")
+        notification = {
+            "id": self._next_id,
+            "organization_id": 1,
+            "type": "app",
+            "title": str(title),
+            "body": body,
+            "data_json": json.dumps(data) if data is not None else None,
+            "source_app_id": plugin_id or None,
+            "action_route": self._resolve_action_route(route, plugin_id),
+            "severity": severity,
+            "is_read": False,
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+        self._next_id += 1
+        print("[palette-notification]", json.dumps(notification, sort_keys=True))
+        return notification
+
+NOTIFICATIONS = LocalNotificationsService()
+
 spec = importlib.util.spec_from_file_location("palette_local_backend", ENTRY)
 module = importlib.util.module_from_spec(spec)
 assert spec and spec.loader
@@ -341,6 +383,7 @@ class DevPluginContextMiddleware(BaseHTTPMiddleware):
         request.state.plugin_local_connections = DEV_CONNECTIONS
         request.state.plugin_apps = LocalAppInteropService()
         request.state.plugin_events = LocalEventPublisher()
+        request.state.notifications = NOTIFICATIONS
         request.state.storage = DEV_STORAGE
         if DEV_REDIS is not None:
             request.state.redis = DEV_REDIS

package/lib/manifest.js

@@ -32,6 +32,8 @@ const TOP_LEVEL_KEYS = new Set([
   "category",
   "tagline",
   "description",
+  "release_notes",
+  "changelog",
   "icon",
   "gradient",
   "sdk",
@@ -526,6 +528,8 @@ function validateManifest(m) {
   requireString(m, "category", "manifest", errors)
   requireString(m, "tagline", "manifest", errors)
   requireString(m, "description", "manifest", errors)
+  requireString(m, "release_notes", "manifest", errors)
+  requireString(m, "changelog", "manifest", errors)
   requireString(m, "icon", "manifest", errors)
 
   if (m.gradient !== undefined) {

package/package.json

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

package/template-fallback/templates/consumer-app/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.24",
+    "@palettelab/sdk": "^0.1.25",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

package/template-fallback/templates/dashboard/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.24",
+    "@palettelab/sdk": "^0.1.25",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/database/package.json

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.24", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.25", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/package.json

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.24", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.25", "react": "^19.0.0" }
 }

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.24",
+    "@palettelab/sdk": "^0.1.25",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/next/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.24",
+    "@palettelab/sdk": "^0.1.25",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/palette-app/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.24",
+    "@palettelab/sdk": "^0.1.25",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/provider-app/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.24",
+    "@palettelab/sdk": "^0.1.25",
     "react": "^19.0.0"
   }
 }