brokenwatch24-jobtread-api

# Skill: JobTread via Pave Query API

## Summary
This skill lets you operate JobTread entirely through openclaw using the Pave-based API at `https://api.jobtread.com/pave`. Every request is a single POST with a `query` object that mirrors GraphQL-style expressions, and you decide which fields you want back. With the right grant key, you can create and manage accounts (customers/vendors), jobs, documents, tasks, locations, custom fields, documents, and even subscribe to webhooks for live updates.

## Setup & Credentials
1. **Create a grant:** Login to https://app.jobtread.com/grants and create a new grant for automation. Copy the one-time `grantKey` (it begins with `grant_` and will only show once).
2. **Store the key locally:** Use a secure file such as `~/.config/jobtread/grant_key`. Example:
   ```bash
   mkdir -p ~/.config/jobtread
   echo "grant_xxx" > ~/.config/jobtread/grant_key
   chmod 600 ~/.config/jobtread/grant_key
   ```
3. **Keep it fresh:** JobTread expires keys after 3 months of inactivity, so schedule a reminder (cron/heartbeat) to rotate or re-use the grant before expiration.
4. **Optional webhook secret:** If you plan to receive webhooks, note your endpoint URL and save the webhook ID in the same folder so you can disable or inspect it later.

## Authentication
- Every POST to `/pave` must include the grant key under `query.$.grantKey`. Example payload:
  ```json
  {
    "query": {
      "$": { "grantKey": "grant_xxx" },
      "currentGrant": { "id": {}, "user": { "name": {} } }
    }
  }
  ```
- You can also set `notify`, `timeZone`, or `viaUserId` inside `$` when you need to suppress notifications or scope results.
- For signed queries (PDF tokens, pre-signed data), call `pdfToken: { _: signQuery, $: { query: {...} } }` and append the token to `https://api.jobtread.com/t/`.

## API Basics & Request Flow
- All requests go to `POST https://api.jobtread.com/pave` with `Content-Type: application/json`.
- Structure:
  ```json
  {
    "query": {
      "$": { "grantKey": "grant_xxx" },  
      "operation": {
        "$": { ...inputs... },
        "field": { ...fields... }
      }
    }
  }
  ```
- Fields you request (`id`, `name`, etc.) determine what JobTread returns. Always include `id` when you plan to reference the object later.
- `_type` in responses tells you the schema for that node.

## Common Patterns & Examples
### 1. Discover your organization ID
```yaml
currentGrant:
  user:
    memberships:
      nodes:
        organization:
          id: {}
          name: {}
```
Use the returned `organization.id` in any following query.

### 2. Create customers/vendors
- **Customer**
```yaml
createAccount:
  $:
    name: "Test Customer"
    type: customer
    organizationId: "ORG_ID"
  createdAccount:
    id: {}
    name: {}
    type: {}
```
- **Vendor** (same as above but `type: vendor`).

### 3. Read or update accounts
- **Read account** by supplying `id` and requesting fields:
```yaml
account:
  $:
    id: "ACCOUNT_ID"
  id: {}
  name: {}
  isTaxable: {}
```
- **Update** and include `customFieldValues` if needed:
```yaml
updateAccount:
  $:
    id: "ACCOUNT_ID"
    isTaxable: false
  account:
    id: {}
    isTaxable: {}
```

### 4. Query accounts list with pagination, sorting, and filters
```yaml
organization:
  $: {}
  id: {}
  accounts:
    $:
      size: 5
      page: "1"
      sortBy:
        - field: type
          order: desc
      where:
        and:
          - - type
            - =
            - customer
          - - name
            - =
            - "Sebas Clients"
    nextPage: {}
    nodes:
      id: {}
      name: {}
      type: {}
```

### 5. Use `where` with `or`, nested fields, or custom fields
- Find account by custom field name:
```yaml
organization:
  $: {}
  id: {}
  contacts:
    $:
      with:
        cf:
          _: customFieldValues
          $:
            where:
              - - customField
                - name
              - "VIP"
            values:
              $:
                field: value
      where:
        - - cf
          - values
        - =
        - "Yes"
    nodes:
      id: {}
      name: {}
```

### 6. Locations and nested filters
Create location and find others tied to the same account:
```yaml
createLocation:
  $:
    accountId: "ACCOUNT_ID"
    name: Test Location
    address: "123 Main St"
  createdLocation:
    id: {}
    name: {}

organization:
  $: {}
  id: {}
  locations:
    $:
      where:
        - - account
          - name
        - Test Name
    nodes:
      id: {}
      name: {}
      account:
        id: {}
        name: {}
```

### 7. Documents, jobs, and aggregates
- Get a job's documents grouped by type/status and sums:
```yaml
job:
  $:
    id: "JOB_ID"
  documents:
    $:
      where:
        - - type
          - in
          - - customerInvoice
            - customerOrder
      group:
        by:
          - type
          - status
        aggs:
          amountPaid:
            sum: amountPaid
          priceWithTax:
            sum: priceWithTax
    withValues: {}
```
- Get document PDF token (append to `https://api.jobtread.com/t/{{token}}`):
```yaml
pdfToken:
  _: signQuery
  $:
    query:
      pdf:
        $:
          id: "DOCUMENT_ID"
```

### 8. Custom fields
- Read a record's custom field values (limit 25 per request):
```yaml
account:
  $:
    id: "ACCOUNT_ID"
  customFieldValues:
    $:
      size: 25
    nodes:
      id: {}
      value: {}
      customField:
        id: {}
```
- Update a custom field via `customFieldValues` map:
```yaml
updateAccount:
  $:
    id: "ACCOUNT_ID"
    customFieldValues:
      "CUSTOM_FIELD_ID": "New value"
  account:
    id: {}
```

### 9. Webhooks
- Use the JobTread UI to create a webhook (Webhooks page) and copy its ID.
- Manage them via the API: list `webhook(id: "ID")` or `deleteWebhook` to cancel.
- Example create query:
```yaml
createWebhook:
  $:
    organizationId: "ORG_ID"
    url: "https://your-endpoint/hooks/jobtread"
    eventTypes:
      - jobCreated
      - documentUploaded
  createdWebhook:
    id: {}
    url: {}
```

## Using This Skill with OpenClaw
- Use `curl` or your preferred HTTP client from OpenClaw's `exec` tool.
- Build the JSON payload as shown (always include the grant key inside `$`).
- You can also wrap the payload in shell variables or helper scripts for portability.
- Save reusable queries in the skill file or separate scripts so Claude or you can call them by name ("run job summary", "create customer", etc.).
- Document each automation in the JobTread vault so you can copy/paste from future sessions without digging through logs.

## Automation Ideas
1. **Nightly job summary:** Query each open job, sum approved customer orders, and store results in Obsidian (or send via WhatsApp).
2. **Webhook monitor:** Automatically spin up a webhook for file uploads and forward notifications to your Slack/WhatsApp via a small server.
3. **Batch account creation:** Feed a CSV of customers/vendors and run `createAccount` for each with the same grant key.
4. **Document check-ins:** Query documents with `status: pending` and send you a summary each morning.

## Troubleshooting & Tips
- **Rate limits:** Grant keys have a throughput cap. If you hit rate limits, add `time.sleep` between requests or batch fewer objects.
- **Missing IDs:** The API complains `id field required` when you forget to request `id`. Always include it when you plan to mutate the record later.
- **Grant expiration:** If a request returns `invalid key`, rotate the grant and update `~/.config/jobtread/grant_key`.
- **Webhooks:** Keep a log of webhook IDs so you can disable or reconfigure them later.
- **Signed tokens:** Use `signQuery` when you need temporary access to document PDFs without storing raw document IDs.