@palettelab/cli 0.3.35 → 0.3.36

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,19 @@ 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`.
 - `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:
 
@@ -524,7 +534,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 +543,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/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:
@@ -666,8 +694,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 +773,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/package.json

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