clawshier

# Receipt Expense Tracker

Process receipt and invoice photos into structured expenses and log them to Google Sheets.

## When to Activate

Activate this skill when the user sends a **photo or image** and any of these apply:

- The message mentions receipts, invoices, expenses, or purchases
- The image appears to be a receipt, invoice, or bill
- The user asks to log, track, or record an expense
- The user asks to add something to their expense spreadsheet

Do **not** activate for images that are clearly not financial documents (memes, screenshots of conversations, etc.).

## Pipeline

Run each step sequentially. If a step fails, retry it up to **2 times** before reporting the error.

### Step 1 — OCR

Save the received image to a temporary file, then extract text:

```bash
node skills/receipt_ocr/handler.js --image <path_to_image>
```

Output schema:

```json
{ "ocr_text": "STARBUCKS\n123 Main St..." }
```

### Step 2 — Structure

Pipe the OCR output to the structurer:

```bash
echo '<step1_output>' | node skills/expense_structurer/handler.js
```

Output schema:

```json
{
  "date": "2026-03-05",
  "vendor": "Starbucks",
  "items": [
    { "description": "Caffe Latte", "quantity": 1, "amount": 5.95 }
  ],
  "subtotal": 5.95,
  "tax": 0.52,
  "total": 6.47,
  "currency": "USD",
  "category": "Food & Drink"
}
```

### Step 3 — Validate

Pipe the structured expense to the validator:

```bash
echo '<step2_output>' | node skills/expense_validator/handler.js
```

This step:
- Generates a SHA-256 fingerprint from `vendor + date + total`
- Checks Google Sheets for duplicate fingerprints
- Normalizes currency codes and trims whitespace
- Validates all required fields are present

If a **duplicate is found**, stop the pipeline and tell the user:

> "This receipt appears to already be logged (vendor, date, total match an existing entry). Skipping."

Output schema (adds `fingerprint` field):

```json
{
  "date": "2026-03-05",
  "vendor": "Starbucks",
  "items": [...],
  "subtot...

# Clawshier

OpenClaw skill that processes receipt/invoice photos from any chat channel, extracts expense data via OpenAI Vision, and logs it to a Google Spreadsheet.

## Prerequisites

- Node.js 18+
- OpenAI API key
- Google Cloud service account with Sheets API enabled

## Install

```bash
git clone https://github.com/YOUR_USER/clawshier.git
cd clawshier
npm install
cp .env.example .env
```

Fill in `.env` with your credentials (see `.env.example`).

### Google Sheets setup

1. Create a Google Cloud service account and download the JSON key file
2. Enable the Google Sheets API in your project
3. Create a spreadsheet and share it with the service account email
4. Add the spreadsheet ID and key file path to `.env`

### OpenClaw usage

Copy `SKILL.md` into your OpenClaw skills directory or install via ClawHub.

## License

MIT