What this skill does

# SKILL: CleanApp Ingest v1 (OpenClaw/ClawHub) This is a **skill package** that lets an agent submit reports into CleanApp using the **Fetcher Key System**: - `POST /v1/fetchers/register` (one-time key issuance) - `POST /v1/reports:bulkIngest` (bulk ingest, quarantine-first) - `GET /v1/fetchers/me` (introspection) This is **not** a long-lived agent running inside the CleanApp backend. It’s a client-side integration that talks to CleanApp over HTTPS. ## Why This Is Safe (Compartmentalized) 1. The only secret in the agent is a **revocable CleanApp API key** (`CLEANAPP_API_TOKEN`). 2. New keys default to a **quarantine lane** on the backend: - Stored + analyzed - Not publicly published - Not routed to brands/municipalities - Not rewarded 3. The backend enforces: - rate limits / quotas - idempotency (`source_id`) - kill switches (revoke/suspend) So even if an agent is prompt-injected, the blast radius is limited to “submitting more quarantined reports” until the key is revoked. ## Required Secret - `CLEANAPP_API_TOKEN` (Bearer token). Get it once via: - `POST /v1/fetchers/register` (see `references/API_REFERENCE.md`) - Store it as a ClawHub/OpenClaw secret; never paste into chat logs. Optional env: - `CLEANAPP_BASE_URL` (default `https://live.cleanapp.io`) ## Data Handling (Minimal by Default) This skill submits: - `title`, `description` (text) - optional `lat`/`lng` (location) - optional `media[]` metadata (URL/SHA/content-type) Recommended low-risk defaults: - `--approx-location` (round coordinates to reduce precision) - `--no-media` (drop media metadata unless needed) ## Idempotency (Important) Every item must include a stable `source_id`. The backend enforces: - `UNIQUE(fetcher_id, source_id)` - retries won’t duplicate rows if you reuse the same `source_id` ## Usage ### Bulk ingest from JSON (recommended) ```bash export CLEANAPP_API_TOKEN="cleanapp_fk_live_..." python3 ingest.py \\ --base-url https://live.cleanapp.io \\ --input examples/sample_items.json \\ --approx-location \\ --no-media ``` ### Dry run (no network) ```bash python3 ingest.py --input examples/sample_items.json --dry-run ``` ### Single-item helper (shell) This is useful for quick manual submissions while debugging. ```bash export CLEANAPP_API_TOKEN="cleanapp_fk_live_..." ./scripts/submit_report.sh --title "Broken elevator" --description "Stuck on floor 3" --lat 34.0702 --lng -118.4441 --approx-location ``` ## Promotion (Out of Quarantine) Promotion is a **reviewed** process. As you build reputation, CleanApp can: - raise caps - allow public publishing/routing/rewards See: - `POST /v1/fetchers/promotion-request` - `GET /v1/fetchers/promotion-status` ## References - Swagger UI: `https://live.cleanapp.io/v1/docs` - OpenAPI YAML: `https://live.cleanapp.io/v1/openapi.yaml` - `references/API_REFERENCE.md` in this package