@cutoffs/openclaw-plugin 0.3.0

package/README.md

@@ -0,0 +1,79 @@
+# Cutoffs OpenClaw Plugin
+
+Third-party OpenClaw plugin that lets OpenClaw talk to external SaaS apps through [Cutoffs](https://cutoffs.dev)'s hosted integration layer.
+
+> **Not affiliated with OpenClaw.** Cutoffs is an independent service. This package is published by the Cutoffs team under the npm scope [`@cutoffs`](https://www.npmjs.com/package/@cutoffs/openclaw-plugin). Source: [public GitHub repository](https://github.com/cutoffs/cutoffs). License: AGPL-3.0.
+
+## What it does
+
+Cutoffs stores provider OAuth tokens and API credentials on Cutoffs servers, encrypted at rest, for a growing catalog of business apps on your behalf. It then exposes a uniform set of tools so OpenClaw can read from and write to those apps without per-provider setup. Today that includes integrations like Google Docs, Google Sheets, Google Calendar, Google Drive, Twilio, and Google Search Console. Setup is browser pairing: OpenClaw opens a Cutoffs approval page, you approve the device once, then return to chat and send `done` so the plugin can store its local Cutoffs device credential safely.
+
+## Install
+
+```bash
+openclaw plugins install clawhub:cutoffs-plugin
+```
+
+Or directly from npm:
+
+```bash
+openclaw plugins install @cutoffs/openclaw-plugin
+```
+
+## Configure
+
+1. In OpenClaw, start browser pairing:
+   - let the assistant call `cutoffs_begin_pairing`
+   - if your session started before the plugin was installed and the tools are not visible yet, start a fresh chat and retry pairing there
+   - if a fresh chat still doesn't show the tools, contact your OpenClaw admin or Cutoffs support to reload the gateway
+2. Open the returned Cutoffs pairing URL in your browser and approve the device.
+3. Go back to OpenClaw and send `done`.
+4. Let the assistant call `cutoffs_get_pairing_status` to finish storing the local credential.
+
+The resulting device credential is stored locally in `~/.openclaw/openclaw.json` under `plugins.entries.cutoffs-plugin.config.apiKey` and is only sent to `cutoffs.dev`.
+
+Full setup walkthrough: https://docs.cutoffs.dev/openclaw
+
+## Tools
+
+The plugin registers ten tools. OpenClaw's assistant discovers available integrations dynamically — you don't need to configure individual apps here.
+
+- `cutoffs_begin_pairing` — start or resume browser pairing for this OpenClaw install
+- `cutoffs_get_pairing_status` — finish pairing after the user returns from the browser and says `done`
+- `cutoffs_start_connection` — start a hosted OAuth/connect session for a new app
+- `cutoffs_get_connection_status` — poll an in-progress connect session
+- `cutoffs_list_integrations` — list apps already connected
+- `cutoffs_list_tools` — list callable tools for one connected app
+- `cutoffs_search_tools` — search connected tools by capability or keyword
+- `cutoffs_describe_tool` — fetch schema and usage guidance for one tool
+- `cutoffs_preview_tool` — preview a tool call before execution, especially for writes
+- `cutoffs_call_tool` — execute a tool against a connected app
+- `cutoffs_get_result` — read a large stored result in slices (path / fields / offset / limit / count)
+
+## File Arguments
+
+Some Cutoffs tools accept file arguments shaped as `{ name, mimetype, s3key }`. When OpenClaw attaches a local file, the plugin reads files only from OpenClaw media directories, rejects path traversal and files over 25 MB, then sends the file bytes to Cutoffs in the request's `files` envelope. Cutoffs stages those bytes with Composio before executing the provider tool, so local OpenClaw attachment paths are not forwarded directly to providers.
+
+If a tool accepts a public URL alternative such as `image_url` or `video_url`, agents may use that instead of a local file attachment.
+
+## Support Commands
+
+Normal onboarding should happen through tools and browser pairing. These commands remain as support/debug escape hatches:
+
+- `/cutoffs pair [deviceLabel]` — start or resume browser pairing from the plugin fast path
+- `/cutoffs pair-status` — check whether browser pairing has been approved yet and finish setup after browser approval
+- `/cutoffs status` — show whether the plugin is paired
+- `/cutoffs logout` — remove the saved credential
+
+## Security
+
+- ClawHub package: `cutoffs-plugin`
+- npm package: `@cutoffs/openclaw-plugin`
+- ClawHub publishes are source-linked to the public GitHub repository and the latest ClawHub security scan is clean.
+- npm releases are published from GitHub Actions with npm provenance.
+- ClawHub verification includes source-linked release metadata for the published artifact.
+- The plugin only makes outbound HTTPS requests to `https://cutoffs.dev`.
+- Browser pairing stores only a local Cutoffs device credential under `~/.openclaw/openclaw.json`.
+- Provider tokens and API keys are not written to OpenClaw config or shown to the assistant; they stay on Cutoffs servers encrypted at rest.
+- The local device credential is sent only as the `X-Cutoffs-API-Key` header to Cutoffs.
+- Report security issues to security@cutoffs.dev.