first commit

packages/openclaw-plugin/README.md

@@ -0,0 +1,78 @@
+# Productier OpenClaw Plugin
+
+This package includes the OpenClaw baseline tools for Productier plus runtime hardening:
+
+- transient retry handling (network + `429/5xx`)
+- per-tool rate limiting
+- structured JSONL audit logging
+
+## Included tools
+
+- `productier_list_workspaces`
+- `productier_list_board_groups`
+- `productier_list_tasks`
+- `productier_list_calendar_events`
+- `productier_list_notes`
+- `productier_list_mailboxes`
+- `productier_list_mail_messages`
+- `productier_list_outgoing_mails`
+- `productier_connect_mailbox`
+- `productier_sync_mailbox`
+- `productier_create_board_group`
+- `productier_create_task`
+- `productier_create_calendar_event`
+- `productier_create_note`
+- `productier_create_outgoing_mail`
+- `productier_create_task_from_mail`
+- `productier_update_board_group`
+- `productier_update_task`
+- `productier_update_calendar_event`
+- `productier_update_note`
+
+Profiles:
+
+- `readonly`: `productier_list_workspaces`, `productier_list_tasks`
+- `standard`: `readonly` tools + board/calendar/notes/task tools + mailbox management + outgoing mail + mail task conversion tools
+
+## Environment
+
+- `PRODUCTIER_API_URL` (default: `http://localhost:8080`)
+- `PRODUCTIER_AUTH_COOKIE` (Better Auth session cookie string used by backend `/v1/*` endpoints)
+- `PRODUCTIER_WORKSPACE_SLUG_DEFAULT` (optional fallback workspace slug)
+- `PRODUCTIER_BOARD_GROUP_ID_DEFAULT` (optional fallback board group id for create-task tool)
+- `PRODUCTIER_TOOL_PROFILE` (`readonly` or `standard`, default `readonly`)
+- `PRODUCTIER_TOOL_RETRY_MAX_ATTEMPTS` (default: `3`)
+- `PRODUCTIER_TOOL_RETRY_BASE_DELAY_MS` (default: `150`)
+- `PRODUCTIER_TOOL_RETRY_MAX_DELAY_MS` (default: `2000`)
+- `PRODUCTIER_TOOL_RETRY_JITTER_MS` (default: `50`)
+- `PRODUCTIER_TOOL_RATE_LIMIT_MAX_CALLS` (default: `120`)
+- `PRODUCTIER_TOOL_RATE_LIMIT_WINDOW_MS` (default: `60000`)
+- `PRODUCTIER_AUDIT_LOG_PATH` (optional JSONL path for per-tool execution audit entries)
+
+## Quick usage
+
+Describe plugin and tool metadata:
+
+```bash
+npm run describe -w packages/openclaw-plugin
+```
+
+Call the tool:
+
+```bash
+node packages/openclaw-plugin/src/cli.mjs call productier_list_tasks '{"workspaceSlug":"personal","limit":20}'
+```
+
+Create a task using defaults:
+
+```bash
+PRODUCTIER_TOOL_PROFILE=standard \
+PRODUCTIER_WORKSPACE_SLUG_DEFAULT=personal \
+PRODUCTIER_BOARD_GROUP_ID_DEFAULT=group-inbox \
+node packages/openclaw-plugin/src/cli.mjs call productier_create_task '{"title":"Write release notes"}'
+```
+
+The tool call returns:
+
+- `ok: true` with `data` on success
+- `ok: false` with structured `error` (`code`, `message`, optional `status`, `requestId`, `attempts`, `retryable`) on failure