sure-api

# Sure API

Use this skill when the user asks to:
- operate **Sure** through its API
- inspect accounts, transactions, categories, tags, merchants, imports, holdings, trades, valuations, or chats
- create/update/delete supported Sure resources safely
- verify whether the upstream Sure API changed
- keep this skill in sync with the official Sure API docs

## Official source-of-truth URLs

These are the URLs the agent should trust first when updating or validating this skill:

- Sure repo: `https://github.com/we-promise/sure`
- API docs directory: `https://github.com/we-promise/sure/tree/main/docs/api`
- OpenAPI spec page: `https://github.com/we-promise/sure/blob/main/docs/api/openapi.yaml`
- Raw OpenAPI download used by the update script: `https://raw.githubusercontent.com/we-promise/sure/main/docs/api/openapi.yaml`

If behavior and local scripts disagree, **re-check the upstream OpenAPI first**.

## Local config

Read secrets from secure env only:
- `SURE_BASE_URL`
- `SURE_API_KEY`

Single source of truth: `secure/api-fillin.env`

Never paste the API key into chat or into non-secure files.

## Auth

Default auth header:
- `X-Api-Key: <SURE_API_KEY>`

Note: the current upstream OpenAPI snapshot also shows `Authorization` header notes on some valuation endpoints. Treat upstream OpenAPI as authoritative if those endpoints behave differently in practice.

## Skill layout

```text
skills/sure-api/
├── SKILL.md
├── references/
│   ├── openapi.yaml
│   └── api_endpoints_summary.md
└── scripts/
    ├── sure_api_request.sh
    ├── sure_api_smoke.sh
    ├── sure_api_cli.js
    ├── sure_openapi_update.sh
    ├── sure_openapi_summarize.js
    └── sure_api_acceptance.sh
```

## Capability model

This skill has **two layers**:

### Layer 1: high-level wrapped commands
Use these first for common operations.

Implemented in `scripts/sure_api_cli.js`:
- `accounts:list`
- `categories:list`
- `tags:list`
- `tags:create`
- `tags:update`
- `tags:delete`
- `merchants:list`
- `transactions:list`
- `transactions:get`
- `transactions:create`
- `transactions:update`
- `transactions:delete`
- `imports:list`
- `holdings:list`
- `trades:list`

### Layer 2: raw official endpoint access
For any official endpoint not yet wrapped by the high-level CLI, use:
- `bash skills/sure-api/scripts/sure_api_request.sh <METHOD> <PATH> [curl args...]`

This means the skill can still operate against official endpoints such as:
- merchant detail
- holding detail
- import detail / create import
- trade create / retrieve / update / delete
- valuation create / retrieve / update
- chats list / create / retrieve / update / delete / send message / retry
- other official endpoints present in `references/openapi.yaml`

## Quick start

### Smoke test

```bash
bash skills/sure-api/scripts/sure_api_smoke.sh
```

### Common wrapped commands

```bash
node skills/sure-api/scripts/sure_api_cli.js accounts:list
node skills/sure-api/scripts/sure_api_cli.js categories:list --classification expense
node skills/sure-api/scripts/sure_api_cli.js tags:list
node skills/sure-api/scripts/sure_api_cli.js merchants:list
node skills/sure-api/scripts/sure_api_cli.js transactions:list --start_date 2026-03-01 --end_date 2026-03-31 --type expense
node skills/sure-api/scripts/sure_api_cli.js holdings:list --account_id <uuid>
node skills/sure-api/scripts/sure_api_cli.js trades:list --account_id <uuid> --start_date 2026-03-01 --end_date 2026-03-31
```

### Safe write pattern

Always prefer:
1. read current state
2. dry-run if the wrapped command supports it
3. send the real write only with explicit confirmation flags

Example:

```bash
node skills/sure-api/scripts/sure_api_cli.js transactions:create \
  --account_id <uuid> \
  --date 2026-03-01 \
  --amount 12.34 \
  --name "午饭" \
  --nature expense \
  --dry-run

node skills/sure-api/scripts/sure_api_cli.js transactions:create \
  --account_id <uuid> \
  --date 2026-03-01 \
  --amount 12.34 \
  --name "午饭" \
  --nature expense \
  --yes
```

## Raw endpoint examples for official API coverage

### Retrieve a merchant by id

```bash
bash skills/sure-api/scripts/sure_api_request.sh GET /api/v1/merchants/<merchant-id>
```

### Retrieve a holding by id

```bash
bash skills/sure-api/scripts/sure_api_request.sh GET /api/v1/holdings/<holding-id>
```

### Retrieve an import by id

```bash
bash skills/sure-api/scripts/sure_api_request.sh GET /api/v1/imports/<import-id>
```

### Create an import from raw CSV content

```bash
bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/imports \
  -H 'Content-Type: application/json' \
  -d '{
    "raw_file_content": "date,amount,name\n2026-03-01,12.34,午饭",
    "type": "TransactionImport",
    "account_id": "<account-uuid>",
    "publish": "true"
  }'
```

### Create a trade

```bash
bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/trades \
  -H 'Content-Type: application/json' \
  -d '{
    "trade": {
      "account_id": "<account-uuid>",
      "date": "2026-03-01",
      "qty": 10,
      "price": 12.5,
      "type": "buy",
      "ticker": "AAPL"
    }
  }'
```

### Create a valuation

```bash
bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/valuations \
  -H 'Content-Type: application/json' \
  -d '{
    "valuation": {
      "account_id": "<account-uuid>",
      "amount": 10000,
      "date": "2026-03-01",
      "notes": "Month-end valuation"
    }
  }'
```

### Create a chat and send a message

```bash
bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/chats \
  -H 'Content-Type: application/json' \
  -d '{"title":"Monthly review","message":"Summarize March spending"}'

bash skills/sure-api/scripts/sure_api_request.sh POST /api/v1/chats/<chat-id>/messages \
  -H 'Content-Type: application/json' \
  -d '{"content":"Show biggest merchant changes"}'
```

## Pagination and filtering

Most list endpoints return a resource list plus a pagination block.
Typical filters in the official API include:
- `page`
- `per_page`
- account/category/merchant/tag ids
- date or date ranges
- type/status filters on some resources

For exact parameters, read `references/openapi.yaml`.

## Error handling

- `401` / `403` → auth missing, invalid, or insufficient feature scope
- `404` → wrong path or object not found
- `422` → validation error; inspect request body against `references/openapi.yaml`
- `429` / `5xx` → retry with backoff up to 3 times if the action is idempotent

## Self-update this skill

This skill is designed to be self-maintainable.

### Fast refresh from official API

```bash
bash skills/sure-api/scripts/sure_openapi_update.sh
```

What it does:
1. downloads the latest official OpenAPI from the Sure GitHub repo
2. overwrites `references/openapi.yaml`
3. regenerates `references/api_endpoints_summary.md`

### After updating OpenAPI

Do this in order:
1. re-read `references/api_endpoints_summary.md`
2. compare new endpoints/params with current `sure_api_cli.js`
3. extend high-level wrappers only for endpoints that are common, stable, and worth scripting
4. keep less-common endpoints accessible via `sure_api_request.sh`
5. run acceptance checks

## When to read references

Read `references/openapi.yaml` when you need:
- exact request bodies
- exact response shapes
- enum values
- parameter names
- authoritative behavior after upstream changes

Read `references/api_endpoints_summary.md` when you need:
- a fast endpoint inventory
- a quick check of what the upstream API currently exposes

## ClawHub publish readiness

Before publishing or bumping a version, run:

```bash
bash skills/sure-api/scripts/sure_api_acceptance.sh
```

Optional live API validation:

```bash
bash skills/sure-api/scripts/sure_api_acceptance.sh --with-live-api
```

The acceptance script checks:
- required files exist
- `SKILL.md` frontmatter is valid enough for publishing
- official URLs are present
- self-update instructions are present
- endpoint summary matches the checked-in OpenAPI
- optional live smoke test passes

## ClawHub publish commands

First confirm login:

```bash
clawhub whoami
```

Initial publish example:

```bash
cd /root/.openclaw/workspace
clawhub publish ./skills/sure-api \
  --slug sure-api \
  --name "Sure API" \
  --version 1.0.0 \
  --changelog "Initial public release." \
  --tags latest
```

Update publish example:

```bash
cd /root/.openclaw/workspace
clawhub publish ./skills/sure-api \
  --slug sure-api \
  --name "Sure API" \
  --version 1.0.1 \
  --changelog "Refresh official OpenAPI, tighten docs, and improve publish readiness." \
  --tags latest
```

## Notes for future maintenance

- Keep `SKILL.md` concise; put exact API detail in `references/`.
- Do not add README / CHANGELOG / extra docs just for packaging.
- Only wrap high-value flows in `sure_api_cli.js`; leave long-tail official endpoints to the raw request wrapper.
- If upstream removes or renames endpoints, update examples and acceptance checks in the same commit.