@palettelab/cli 0.3.35 → 0.3.37

package/README.md

@@ -275,7 +275,8 @@ async def create_invoice(body: InvoiceIn, ctx: PluginContext = Depends(get_plugi
 
 Backend SDK features for app-owned data:
 
-- `PluginContext` exposes `user_id`, `organization_id`, `plugin_id`, `permissions`, `config`, `storage`, `ctx.db`, `ctx.members`, `ctx.redis`, and `ctx.vector`.
+- `PluginRouter`, `PluginContext`, and `get_plugin_context` provide the FastAPI route and request-context surface.
+- `PluginContext` exposes `user_id`, `organization_id`, `org_role`, `plugin_id`, `permissions`, `storage`, `ctx.db`, `ctx.data_rooms`, `ctx.members`, `ctx.redis`, `ctx.vector`, `ctx.config`, and `ctx.logger`.
 - `ctx.db` is the full scoped SQLAlchemy `AsyncSession` for app-owned database data.
 - `ctx.repo(Model)` gives org-safe CRUD helpers for app tables.
 - `ctx.data_rooms` gives backend access to Palette Data Rooms without importing platform internals.
@@ -283,10 +284,20 @@ Backend SDK features for app-owned data:
 - `ctx.has_permission("...")`, `ctx.has_any_permission([...])`, and `ctx.has_all_permissions([...])` check declared permissions.
 - `ctx.config_value("key")` and `ctx.require_config("key")` read app install/config values.
 - `ctx.secret("KEY")` reads app secrets from config or environment variables.
+- `get_config(ctx, key)` and `require_config(ctx, key)` are functional config helper forms.
+- `require_permission(permission)`, `KNOWN_PERMISSIONS`, and `is_known_permission(permission)` support route and manifest permission checks.
 - `ctx.redis` gives a Redis-backed, plugin/org-scoped Redis API when `"redis"` is declared in `platform_services`.
 - `ctx.vector` gives a Qdrant-backed, plugin/org-scoped vector API when `"vector"` is declared in `platform_services`.
+- `ctx.storage` gives app/org-scoped file upload helpers when `"storage"` is declared in `platform_services`.
 - `LifecycleHooks` lets apps define install/update/enable/disable/uninstall hooks.
 - `OrgScopedTable` and `PluginBase` keep app data inside the plugin schema model set.
+- `plugin_safe_id(...)`, `plugin_schema(...)`, `plugin_table_prefix(...)`, and `ensure_org_rls(...)` keep database names and row-level security consistent.
+- `Event` and `subscribe_event(...)` register in-process platform event handlers.
+- `sign_webhook(...)` and `verify_webhook_signature(...)` handle HMAC-SHA256 webhook signing checks.
+- `ToolDefinition` is the base class for custom agent tools.
+- `PluginManifest` and `load_manifest(...)` parse and validate `palette-plugin.json`.
+- `SuccessResponse`, `ErrorResponse`, and `PaginatedResponse` are reusable response schemas.
+- `route_permission_issues(router, public_routes=None)` is the test helper for detecting ungated backend routes.
 
 Python backend Data Room example:
 
@@ -316,6 +327,24 @@ async def sync_invoices(ctx: PluginContext = Depends(get_plugin_context)):
     return {"room": room, "folder": folder, "bytes": len(content or b"")}
 ```
 
+Python backend app-storage example:
+
+```python
+@router.post("/reports", dependencies=[require_permission("reports:write")])
+async def save_report(ctx: PluginContext = Depends(get_plugin_context)):
+    saved = await ctx.storage.upload_file(
+        "summary.json",
+        b'{"ok": true}',
+        "application/json",
+        key="reports/summary.json",
+    )
+    return saved
+```
+
+Frontend apps can use `createPaletteClient(platform).storage.upload(file, {
+onProgress })`. Palette writes every object under the app folder and current
+organisation folder, then uses GCS resumable uploads in hosted environments.
+
 The npm `@palettelab/sdk` package is for frontend JavaScript/React apps.
 Python backend code uses `palette_sdk`, which is embedded in the CLI for
 local dev/tests and injected by the hosted Palette runtime.
@@ -524,7 +553,7 @@ await ctx.redis.incr("counter")
 await ctx.redis.decr("counter")
 await ctx.redis.scan(prefix="cache:", limit=100)
 
-# Redis hashes, lists, sets, sorted sets, streams, locks
+# Redis hashes, lists, sets, sorted sets, queues, locks
 await ctx.redis.hset("hash", "field", {"value": 1})
 await ctx.redis.hgetall("hash")
 await ctx.redis.lpush("queue", {"job": 1})
@@ -533,8 +562,8 @@ await ctx.redis.sadd("tags", "red", "blue")
 await ctx.redis.smembers("tags")
 await ctx.redis.zadd("scores", {"alice": 10})
 await ctx.redis.zrange("scores", 0, -1, with_scores=True)
-await ctx.redis.xadd("events", {"type": "created"})
-await ctx.redis.xread({"events": "0-0"}, count=10)
+await ctx.redis.enqueue("jobs", {"task": "sync"})
+await ctx.redis.dequeue("jobs")
 await ctx.redis.lock("invoice:1", token, ttl=30)
 await ctx.redis.unlock("invoice:1", token)
 

package/backend-sdk/palette_sdk/__init__.py

@@ -36,6 +36,7 @@ from palette_sdk.events import Event, subscribe_event
 from palette_sdk.config import get_config, require_config
 from palette_sdk.webhooks import sign_webhook, verify_webhook_signature
 from palette_sdk.testing import route_permission_issues
+from palette_sdk.storage import LocalStorageService
 
 __all__ = [
     "PluginRouter",
@@ -72,6 +73,7 @@ __all__ = [
     "sign_webhook",
     "verify_webhook_signature",
     "route_permission_issues",
+    "LocalStorageService",
 ]
 
-__version__ = "0.1.7"
+__version__ = "0.1.8"

package/backend-sdk/palette_sdk/plugin_context.py

@@ -111,7 +111,7 @@ async def get_plugin_context(request: Request) -> PluginContext:
         org_role=getattr(state, "org_role", None),
         plugin_id=getattr(state, "plugin_id", ""),
         permissions=getattr(state, "plugin_permissions", []),
-        storage=getattr(state, "storage", None),
+        storage=getattr(state, "storage", None) or UnavailablePlatformService("storage"),
         data_rooms=DataRoomsClient(getattr(state, "data_rooms", None)),
         members=OrganizationMembersClient(
             getattr(state, "org_members", None),

package/backend-sdk/palette_sdk/storage.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import mimetypes
+import re
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+def _slug_segment(value: str | None, fallback: str) -> str:
+    raw = (value or fallback).strip().lower()
+    slug = re.sub(r"[^a-z0-9]+", "_", raw).strip("_")
+    return slug or fallback
+
+
+def _sanitize_filename(filename: str | None) -> str:
+    raw = (filename or "upload").strip().replace("\\", "/").rsplit("/", 1)[-1]
+    safe = re.sub(r"[^\w.\- ]+", "", raw)
+    safe = re.sub(r"\s+", "_", safe).strip("._")
+    return safe or "upload"
+
+
+def _validate_relative_key(key: str) -> str:
+    key = key.strip().replace("\\", "/")
+    if not key or key.startswith("/") or key.endswith("/"):
+        raise ValueError("key must be a non-empty relative file path")
+    parts = [part for part in key.split("/") if part]
+    if any(part in {".", ".."} for part in parts):
+        raise ValueError("key cannot contain relative path segments")
+    return "/".join(_sanitize_filename(part) for part in parts)
+
+
+def _content_type(filename: str | None, content_type: str | None) -> str:
+    browser_ct = content_type or "application/octet-stream"
+    if browser_ct == "application/octet-stream":
+        guessed, _ = mimetypes.guess_type(filename or "")
+        return guessed or browser_ct
+    return browser_ct
+
+
+@dataclass
+class LocalStorageService:
+    """Filesystem-backed ctx.storage implementation used by local SDK dev."""
+
+    root: str | Path
+    plugin_id: str
+    app_name: str | None = None
+    organization_id: int = 1
+    organization_slug: str | None = "palette-dev"
+    organization_name: str | None = "Palette Dev"
+
+    def _prefix(self) -> str:
+        app_folder = f"{_slug_segment(self.app_name or self.plugin_id, 'app')}_{_slug_segment(self.plugin_id, 'plugin')}"
+        org_label = self.organization_slug or self.organization_name or f"org_{self.organization_id}"
+        org_folder = f"{_slug_segment(org_label, 'organisation')}_{self.organization_id}"
+        return f"uploads/apps/{app_folder}/{org_folder}"
+
+    def object_path(self, filename: str | None = None, *, key: str | None = None) -> str:
+        relative = _validate_relative_key(key) if key else f"{uuid.uuid4().hex}_{_sanitize_filename(filename)}"
+        return f"{self._prefix()}/{relative}"
+
+    def _target(self, object_path: str) -> Path:
+        root = Path(self.root).resolve()
+        target = (root / object_path).resolve()
+        target.relative_to(root)
+        return target
+
+    async def upload_file(
+        self,
+        filename: str,
+        content: bytes,
+        content_type: str | None = None,
+        *,
+        key: str | None = None,
+    ) -> dict[str, Any]:
+        object_path = self.object_path(filename, key=key)
+        target = self._target(object_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+        return {
+            "bucket": "local",
+            "object_path": object_path,
+            "file_url": target.as_uri(),
+            "content_type": _content_type(filename, content_type),
+            "size": len(content),
+        }
+
+    async def create_resumable_upload(
+        self,
+        filename: str,
+        content_type: str | None = None,
+        size: int | None = None,
+        *,
+        key: str | None = None,
+    ) -> dict[str, Any]:
+        object_path = self.object_path(filename, key=key)
+        return {
+            "bucket": "local",
+            "object_path": object_path,
+            "file_url": self._target(object_path).as_uri(),
+            "upload_url": None,
+            "content_type": _content_type(filename, content_type),
+            "size": size,
+        }

package/backend-sdk/pyproject.toml

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

package/docs/python-backend-sdk.md

@@ -125,6 +125,34 @@ Available context values:
 | `ctx.require_config(key)` | Read required config or raise |
 | `ctx.secret(key, default)` | Read a secret from app config or environment |
 
+## 4a. Backend Helper API Index
+
+These are the public Python helpers exported by `palette_sdk`.
+
+| Helper | Use it for |
+|---|---|
+| `PluginRouter` | FastAPI router mounted under `/api/v1/plugins/<plugin-id>` |
+| `PluginContext`, `get_plugin_context` | Authenticated request context dependency |
+| `MissingSecretError` | Handling missing required declared secrets from `ctx.secret(...)` |
+| `require_permission(permission)` | Route-level permission gate required for protected routes |
+| `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 |
+| `OrgRepository`, `ctx.repo(Model)` | Org-safe convenience CRUD for app-owned models |
+| `PluginBase`, `OrgScopedTable` | SQLAlchemy declarative bases for plugin-owned tables |
+| `ensure_org_rls(op, table)` | Alembic helper that enables org row-level security |
+| `plugin_safe_id(...)`, `plugin_schema(...)`, `plugin_table_prefix(...)` | Manifest id to database-safe naming helpers |
+| `get_config(ctx, key)`, `require_config(ctx, key)` | Functional form of config reads when not using `ctx.config_value(...)` |
+| `LocalRedisService`, `LocalVectorService` | Local `pltt dev` service emulators and test fakes |
+| `PlatformServiceUnavailable`, `UnavailablePlatformService` | Clear errors when an undeclared platform service is used |
+| `LifecycleHooks` | Install/update/enable/disable/uninstall callbacks |
+| `Event`, `subscribe_event(...)` | In-process platform event subscriptions |
+| `sign_webhook(...)`, `verify_webhook_signature(...)` | HMAC-SHA256 webhook signing and verification |
+| `ToolDefinition` | Base class for custom agent tools |
+| `PluginManifest`, `load_manifest(...)` | Typed manifest parsing from `palette-plugin.json` |
+| `SuccessResponse`, `ErrorResponse`, `PaginatedResponse` | Common response schemas for plugin APIs |
+| `route_permission_issues(router, public_routes=None)` | Test helper that reports routes missing `require_permission(...)` |
+
 ## 5. Permissions
 
 Use route-level permission guards for normal APIs:
@@ -603,11 +631,11 @@ install config, plugin-scope encrypted secrets, or local `.palette/.env.local`
 during `pltt dev`. Undeclared keys still fall back to the process environment
 for local compatibility.
 
-Managed Redis and vector services are declared in the manifest:
+Managed Redis, vector, and storage services are declared in the manifest:
 
 ```json
 {
-  "platform_services": ["redis", "vector"]
+  "platform_services": ["redis", "vector", "storage"]
 }
 ```
 
@@ -626,6 +654,43 @@ Palette scopes every Redis key and vector operation by `plugin_id` and
 `organization_id`; hosted previews also include the publish id. Plugin code
 cannot read, list, update, or delete records owned by another app or org.
 
+Palette scopes storage the same way. Files written through `ctx.storage` or the
+frontend storage client live under:
+
+```text
+uploads/apps/{app_name}_{plugin_id}/{organisation_slug}_{organisation_id}/{file}
+```
+
+Backend storage helpers:
+
+```python
+saved = await ctx.storage.upload_file(
+    "summary.json",
+    b'{"ok": true}',
+    "application/json",
+    key="reports/summary.json",
+)
+
+session = await ctx.storage.create_resumable_upload(
+    "video.mp4",
+    "video/mp4",
+    size=video_size,
+    key="videos/video.mp4",
+)
+```
+
+Frontend apps can use the browser SDK for chunked/resumable upload progress:
+
+```tsx
+const palette = createPaletteClient(platform)
+
+await palette.storage.upload(file, {
+  key: `videos/${file.name}`,
+  chunkSize: 8 * 1024 * 1024,
+  onProgress: (p) => setPercent(p.percentage),
+})
+```
+
 Advanced provider features are still available through scoped helpers:
 `ctx.redis.execute(...)` forwards Redis data-plane commands after key rewriting,
 while blocking server/admin commands. `ctx.vector.client()` returns the Qdrant
@@ -666,8 +731,6 @@ await ctx.redis.zrem("scores", "bob")
 
 await ctx.redis.enqueue("jobs", {"task": "sync"})
 await ctx.redis.dequeue("jobs")
-await ctx.redis.xadd("events", {"type": "created"})
-await ctx.redis.xread({"events": "0-0"}, count=10)
 await ctx.redis.lock("invoice:1", token, ttl=30)
 await ctx.redis.unlock("invoice:1", token)
 ```
@@ -747,12 +810,10 @@ Frontend code should call backend routes through the platform API helper, not by
 hardcoding backend origins.
 
 ```tsx
-import { createPaletteClient } from "@palettelab/sdk"
-
-const palette = createPaletteClient()
+import { apiFetch } from "@palettelab/sdk"
 
 async function loadInvoices() {
-  const res = await palette.apiFetch("/api/v1/plugins/finance-tools/invoices")
+  const res = await apiFetch("/api/v1/plugins/finance-tools/invoices")
   return res.json()
 }
 ```

package/lib/dev-simulator.js

@@ -134,12 +134,23 @@ sys.path.insert(0, str(ENTRY.parent))
 
 DEV_REDIS = None
 DEV_VECTOR = None
+DEV_STORAGE = None
 if _service_enabled("redis"):
     from palette_sdk.platform_services import LocalRedisService
     DEV_REDIS = LocalRedisService()
 if _service_enabled("vector"):
     from palette_sdk.platform_services import LocalVectorService
     DEV_VECTOR = LocalVectorService()
+if _service_enabled("storage"):
+    from palette_sdk.storage import LocalStorageService
+    DEV_STORAGE = LocalStorageService(
+        ROOT / ".palette" / "dev-storage",
+        MANIFEST.get("id", ""),
+        app_name=MANIFEST.get("name"),
+        organization_id=1,
+        organization_slug="palette-dev",
+        organization_name="Palette Dev",
+    )
 
 spec = importlib.util.spec_from_file_location("palette_local_backend", ENTRY)
 module = importlib.util.module_from_spec(spec)
@@ -178,7 +189,7 @@ class DevPluginContextMiddleware(BaseHTTPMiddleware):
             "secret_specs": MANIFEST.get("secrets") or {},
             "secret_scope": "dev",
         }
-        request.state.storage = None
+        request.state.storage = DEV_STORAGE
         if DEV_REDIS is not None:
             request.state.redis = DEV_REDIS
         if DEV_VECTOR is not None:

package/package.json

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

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.12"
+    "@palettelab/sdk": "^0.1.15"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/template-fallback/palette-plugin.json

@@ -13,7 +13,7 @@
     "text": "#fff"
   },
   "sdk": {
-    "frontend": "^0.1.12",
+    "frontend": "^0.1.15",
     "backend": "^0.1.0"
   },
   "platform": {

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

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

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

@@ -9,7 +9,7 @@
   "description": "A widget that exposes a dashboard data source and renders a chart from it.",
   "icon": "ChartBar",
   "gradient": { "bg": "linear-gradient(135deg, #06B6D4, #6366F1)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.15", "backend": "^0.1.8" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

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.12", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.15", "react": "^19.0.0" }
 }

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

@@ -9,7 +9,7 @@
   "description": "Stores notes per organization with RLS-enforced isolation.",
   "icon": "Database",
   "gradient": { "bg": "linear-gradient(135deg, #8B5CF6, #EC4899)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.15", "backend": "^0.1.8" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

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.12", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.15", "react": "^19.0.0" }
 }

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

@@ -9,7 +9,7 @@
   "description": "Demonstrates declared external_network access and a scoped per-org config token.",
   "icon": "CloudArrowUp",
   "gradient": { "bg": "linear-gradient(135deg, #10B981, #06B6D4)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.15", "backend": "^0.1.8" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

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

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

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

@@ -9,7 +9,7 @@
   "description": "A frontend-only plugin — renders inside the platform iframe sandbox with no backend.",
   "icon": "Puzzle",
   "gradient": { "bg": "linear-gradient(135deg, #6366F1, #8B5CF6)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12" },
+  "sdk": { "frontend": "^0.1.15" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

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

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

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

@@ -9,7 +9,7 @@
   "description": "Uses frontend.framework=next so pltt reads frontend/next.config.ts while still publishing a native Palette module.",
   "icon": "Puzzle",
   "gradient": { "bg": "linear-gradient(135deg, #0F766E, #2563EB)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.12" },
+  "sdk": { "frontend": "^0.1.15" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,