meerkat-agents 0.1.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ba46da11751ebb2b4dc36e5c02c9ef99add0b0507822637a7ad343f97498ff
-  data.tar.gz: edeb9fc5d5c08e3b44263460ace6591ebf81ec2187477cb69e2d0b1069df2925
+  metadata.gz: '0151964121201f009fe0a38729a847a3b45e7ba6521f10a374936f563fcdef17'
+  data.tar.gz: 31d8cd573baf1ff066769e8fa30564ac421828d1da6b4ef098aaf66b0758748a
 SHA512:
-  metadata.gz: c6cad6d121752a4438682e854346b680781b916540cdf184b9556042326f865a4bda00ea3fa993010f59f6de762956dbe3be9d604a082f8cd202882ac6aa3bbf
-  data.tar.gz: 6addcf95c8bab0591ec242814960bb79e54e9b97043cc85888aea0ebf4fc0628a3a751db0cedc756d1645e9712200e1e0a3046362c92e3a479a4afcba13017b6
+  metadata.gz: 13b749556fee04012ded622626e438e701afe51e0ae1d820ccfeb9f5e9136fb337317aa0c6f2464ad03205df67cdc1731c75226725b3d3b35354194e81eb6f62
+  data.tar.gz: f5e6b21b1aaeea6610af91bdf1f6edfa9b06c8880efa82ae02060c994ad9a4adfa51e5cea9bf1c544422b330ef6a0de8c394acb1fc761162a9cb04c26ee95d71

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-07-17
+
+### Changed
+
+- RubyGems summary/description rewritten around the problem, use cases, and how Meerkat differs from Sidekiq / Active Job / queue gems (no pricing copy)
+- Homepage and documentation URIs point to https://cloud.meerkatagents.com/docs/introduction
+
+## [0.3.0] - 2026-07-16
+
+### Added
+
+- `client.monitors` resource against `/api/v1/monitors` (create, list, retrieve, update, delete, pause, resume, run, runs, retrieve_run, artifacts, events)
+- `client.tasks` remains as a deprecated alias of `client.monitors`
+
+### Changed
+
+- Primary API surface is Change Intelligence **monitors** (always recurring; no `task_type` on create)
+- README and gemspec copy updated for Cloud monitors + webhooks
+
+## [0.2.0] - 2026-07-09
+
+### Added
+
+- `Meerkat::SubscriptionRequiredError` for HTTP 402 (free plan limits)
+- Signup requires `company` and `website`
+
+### Changed
+
+- RubyGems homepage and documentation URIs point to Cloud docs (`cloud.meerkatagents.com/docs/sdk-ruby`)
+- README is Cloud-first: install → signup → LLM key → create monitor → subscribe
+
 ## [0.1.1] - 2026-06-27
 
 ### Changed
@@ -20,5 +51,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Webhook HMAC-SHA256 verification helpers
 - Optional Rails railtie and webhook verification concern
 
+[0.3.1]: https://github.com/Tiny-Bubble-Company/meerkat-ruby/releases/tag/v0.3.1
+[0.3.0]: https://github.com/Tiny-Bubble-Company/meerkat-ruby/releases/tag/v0.3.0
+[0.2.0]: https://github.com/Tiny-Bubble-Company/meerkat-ruby/releases/tag/v0.2.0
 [0.1.1]: https://github.com/Tiny-Bubble-Company/meerkat-ruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/Tiny-Bubble-Company/meerkat-ruby/releases/tag/v0.1.0

data/README.md

@@ -1,410 +1,61 @@
-<p align="center">
-  <a href="https://meerkatagents.com">
-    <img src=".github/readme-banner.png" alt="Meerkat — open source webhook-native agent task API" width="100%">
-  </a>
-</p>
-
-<p align="center">
-  <img src=".github/meerkat-logo.png" alt="Meerkat mascot" width="88" height="88">
-  <br>
-  <em>Describe a task in plain English. Meerkat runs it async — results POST to your webhook.</em>
-</p>
-
 # meerkat-agents
 
-Official Ruby client for [Meerkat](https://github.com/Tiny-Bubble-Company/meerkat) — an open source, webhook-native API for async agent tasks.
-
-Install as **`meerkat-agents`**, require as **`meerkat`**:
-
-```ruby
-gem "meerkat-agents"
-# ...
-require "meerkat"
-```
-
-[![Gem Version](https://badge.fury.io/rb/meerkat-agents.svg)](https://badge.fury.io/rb/meerkat-agents)
-[![License: MIT](https://img.shields.io/badge/License-MIT-111111.svg)](LICENSE)
-
----
-
-## About Meerkat
-
-**Meerkat** is open source infrastructure for async agent tasks. You describe work in plain English, connect your own LLM key (BYOK), and Meerkat schedules execution and POSTs signed JSON to your webhook — without building schedulers, scrapers, or retry logic.
-
-| Resource | Link |
-|----------|------|
-| **Website** | [meerkatagents.com](https://meerkatagents.com) |
-| **Documentation** | [meerkatagents.com/docs](https://meerkatagents.com/docs) |
-| **Use cases** | [Package tracking](https://meerkatagents.com/use-cases/package-tracking) · [Site monitoring](https://meerkatagents.com/use-cases/website-monitoring) · [Agent webhooks](https://meerkatagents.com/use-cases/agent-webhooks) |
-| **Developer guides** | [meerkatagents.com/blog](https://meerkatagents.com/blog) |
-| **Sign up (Cloud)** | [cloud.meerkatagents.com/signup](https://cloud.meerkatagents.com/signup) |
-| **Open source server** | [github.com/Tiny-Bubble-Company/meerkat](https://github.com/Tiny-Bubble-Company/meerkat) |
-
-**This repo** is the official **Ruby gem** (`meerkat-agents` on RubyGems). For product overview, use cases, and self-host vs Cloud, read more on the [Meerkat website](https://meerkatagents.com).
-
-**Other SDKs:** [meerkat-python](https://github.com/Tiny-Bubble-Company/meerkat-python) · [meerkat-javascript](https://github.com/Tiny-Bubble-Company/meerkat-javascript)
-
----
-
-## Table of contents
-
-- [About Meerkat](#about-meerkat)
-- [What is Meerkat?](#what-is-meerkat)
-- [What problem does it solve?](#what-problem-does-it-solve)
-- [Why use this gem?](#why-use-this-gem)
-- [How it works](#how-it-works)
-- [Use cases](#use-cases)
-- [Task types](#task-types)
-- [Self-host vs Meerkat Cloud](#self-host-vs-meerkat-cloud)
-- [Installation](#installation)
-- [Quick start](#quick-start)
-- [Examples](#examples)
-- [Receiving webhooks (Rails)](#receiving-webhooks-rails)
-- [Output formats](#output-formats)
-- [API reference](#api-reference)
-- [Configuration](#configuration)
-- [Development](#development)
-- [License](#license)
-
----
-
-## What is Meerkat?
-
-Meerkat gives developers a single primitive for agentic async work:
-
-```
-Register a task → Meerkat runs it → findings POST to your webhook
-```
-
-Describe a task in plain English, pass structured `input_params`, bring your own LLM key (BYOK), and Meerkat's agent executes the work — fetching webpages, extracting structured findings, and delivering JSON to your `output_webhook` on a schedule or on demand.
-
-**No polling. No per-carrier SDKs. No LLM tool loops to maintain.**
-
-This gem wraps the Meerkat REST API so you can create tasks, trigger runs, and verify inbound webhooks from Ruby and Rails apps without hand-rolling HTTP clients.
-
----
-
-## What problem does it solve?
-
-Building async agent workflows usually means stitching together:
-
-- A job queue and scheduler
-- LLM calls with tool use (fetch URL, parse HTML, compare state)
-- Webhook delivery and retry logic
-- Change detection between runs
-
-Meerkat handles all of that as a managed API. **meerkat-agents** handles the client side:
-
-| Without the gem | With meerkat-agents |
-|-----------------|-------------------|
-| Raw `curl` / Faraday calls | Typed resource methods (`client.tasks.create`, `client.tasks.run`) |
-| Manual auth headers | API key configured once |
-| DIY webhook HMAC verification | `Meerkat::Webhooks.verify` + Rails concern |
-| Error parsing by hand | `Meerkat::NotFoundError`, `ValidationError`, etc. |
-
----
-
-## Why use this gem?
-
-- **Webhook-native** — every task delivers JSON to your endpoint; the gem helps you verify signatures
-- **BYOK** — Anthropic, OpenAI, OpenRouter, or Grok; keys stored on your Meerkat account
-- **Recurring + one-off** — natural-language schedules (`every 2 hours`) or ad-hoc runs
-- **Self-host or Cloud** — same API against Docker, Render, Fly.io, or [Meerkat Cloud](https://cloud.meerkatagents.com/signup)
-- **Rails-ready** — optional railtie, env-based config, webhook verification concern
-
----
-
-## How it works
-
-```
-┌─────────────┐     client.tasks.create   ┌─────────────┐     agent + tools    ┌─────────────┐
-│  Your app   │ ───────────────────────►  │   Meerkat   │ ──────────────────►  │  Web / APIs │
-└─────────────┘                           └─────────────┘                      └─────────────┘
-       ▲                                          │
-       │              POST output_webhook         │
-       └──────────────────────────────────────────┘
-              (verify with Meerkat::Webhooks)
-```
-
-| Step | What happens |
-|------|--------------|
-| **1. Register** | `client.tasks.create(...)` — describe work, pass params, set webhook |
-| **2. Run** | Meerkat schedules recurring tasks or runs one-offs on demand |
-| **3. Receive** | Findings POSTed to your webhook as structured JSON |
-
----
-
-## Use cases
-
-What teams ship with Meerkat — aligned with the [use cases on meerkatagents.com](https://meerkatagents.com):
-
-| Use case | In one line | On the website |
-|----------|-------------|----------------|
-| **Package tracking** | Webhook when DHL, UPS, FedEx, or any carrier status changes | [Package tracking →](https://meerkatagents.com/use-cases/package-tracking) |
-| **Website monitoring** | Watch a URL; get notified when the signal you describe happens | [Site monitoring →](https://meerkatagents.com/use-cases/website-monitoring) |
-| **Price & stock** | Competitor price drops and restocks without building a scraper | [Guide →](https://meerkatagents.com/blog/competitor-price-stock-monitoring) |
-| **Async agent webhooks** | Register LLM agent work; results POST to your endpoint | [Agent webhooks →](https://meerkatagents.com/use-cases/agent-webhooks) |
-
-Read the full [developer guides](https://meerkatagents.com/blog) for step-by-step tutorials with API examples.
-
----
-
-### Package tracking — webhook when status changes
-
-Monitor any courier tracking link — DHL, UPS, FedEx, USPS, DPD, Royal Mail — with **one API**. Meerkat's agent reads the carrier page on a schedule, detects state changes, and POSTs structured JSON to your endpoint. No per-carrier SDKs, no polling loops, no LLM tool code to maintain.
-
-- **Every carrier, one endpoint** — pass a `courier_tracking_link`; adding a new carrier is zero integration code.
-- **Webhook on change only** — hear from Meerkat when status moves (*In transit → Out for delivery → Delivered*), not on every poll.
-- **Signed and retried** — HMAC-SHA256 signatures, exponential backoff, delivery history via the events API.
-
-```ruby
-client.tasks.create(
-  task_type: "recurring",
-  description: "Monitor DHL tracking and report status changes",
-  input_params: { courier_tracking_link: "https://www.dhl.de/track?id=..." },
-  frequency: "every 2 hours",
-  output_webhook: "https://your-app.com/webhooks/meerkat"
-)
-```
-
-→ [Package tracking use case](https://meerkatagents.com/use-cases/package-tracking) · [Shipment tracking guide](https://meerkatagents.com/blog/shipment-tracking-api-webhook)
-
----
-
-### Website monitoring — watch any URL
-
-A change-detection API that understands **intent**, not just pixel diffs. Describe the signal in plain English — *price under $99*, *plan name changed*, *status page updated* — and Meerkat watches on a schedule. It only fires your webhook when that condition is met.
-
-- **Semantic, not cosmetic diff** — no CSS selectors to maintain when the page layout shifts.
-- **JS-rendered pages** — SPAs and dynamic content via headless fetch before reasoning.
-- **Your schedule** — natural language (`every 15 minutes`), cron, or on-demand `client.tasks.run(id)`.
-
-```ruby
-client.tasks.create(
-  task_type: "recurring",
-  description: "Notify me when this product drops below $99",
-  input_params: { url: "https://shop.example.com/widget-pro" },
-  frequency: "every 30 minutes",
-  output_webhook: "https://your-app.com/webhooks/meerkat"
-)
-```
-
-→ [Website monitoring use case](https://meerkatagents.com/use-cases/website-monitoring) · [Monitor website for changes guide](https://meerkatagents.com/blog/monitor-website-for-changes)
-
----
-
-### Price & stock monitoring — competitor alerts
-
-Track competitor product pages and get a signed webhook when **price drops**, **price increases**, or **stock flips** (out of stock → in stock). One task per SKU — no scraper fleet, scheduler, or retry layer to operate.
-
-```ruby
-client.tasks.create(
-  task_type: "recurring",
-  description: "Report price and stock whenever either changes",
-  input_params: { url: "https://competitor.com/product/sku-123" },
-  frequency: "every 15 minutes",
-  output_webhook: "https://your-app.com/webhooks/meerkat"
-)
-```
-
-Example webhook when price moves:
-
-```json
-{
-  "data": {
-    "summary": "Price dropped from 99.00 to 89.00",
-    "findings": { "price": 89.0, "previous_price": 99.0, "in_stock": true },
-    "change_detected": true
-  }
-}
-```
-
-→ [Competitor price & stock guide](https://meerkatagents.com/blog/competitor-price-stock-monitoring)
-
----
-
-### Async agent webhooks — skip the scheduler boilerplate
-
-Meerkat is the open source primitive for engineers who would rather ship product than rebuild **schedulers, LLM tool loops, retries, and signed webhook delivery**. Register a task in plain English, attach your LLM key (BYOK), point at an endpoint — done.
-
-- **One verb: register** — `POST /tasks` creates recurring or one-off agent work.
-- **Webhook-native results** — structured JSON, signed, retried until 2xx (same contract as Stripe or GitHub webhooks).
-- **MIT & self-hostable** — Docker, Render, Fly.io, or Meerkat Cloud; identical REST API.
-
-```ruby
-client.tasks.create(
-  task_type: "recurring",
-  description: "Summarize new arXiv papers in distributed systems",
-  input_params: { topic: "distributed systems" },
-  frequency: "0 9 * * *",
-  output_webhook: "https://your-app.com/webhooks/meerkat"
-)
-```
-
-→ [Agent webhooks use case](https://meerkatagents.com/use-cases/agent-webhooks) · [Webhook vs polling guide](https://meerkatagents.com/blog/webhook-vs-polling)
-
----
-
-### One-off lookups
-
-Ad-hoc agent tasks without standing up a schedule — research, single URL extraction, or on-demand runs triggered from your app:
-
-```ruby
-client.tasks.create(
-  task_type: "one_off",
-  description: "Fetch the current price of this product once",
-  input_params: { url: "https://example.com/product/123" },
-  output_webhook: "https://your-app.com/webhooks/meerkat"
-)
-```
-
----
-
-### Scheduled scraping with webhooks
-
-Need data on a cadence, not just change detection? Set a frequency and receive structured findings every run — see the [web scraping API guide](https://meerkatagents.com/blog/web-scraping-api-scheduled-webhooks).
-
----
-
-## Task types
-
-| Type | Behavior | Best for |
-|------|----------|----------|
-| `recurring` | Runs on a schedule; compares state between runs; reports changes | Courier tracking, uptime, price watches |
-| `one_off` | Runs once, reports findings, marks task complete | Ad-hoc research, single lookups |
-
-**Frequency** accepts natural language (`every 30 minutes`, `hourly`, `every 2 hours`) or cron expressions. Required for `recurring` tasks; omit for `one_off`.
-
----
-
-## Self-host vs Meerkat Cloud
-
-| | Self-host (OSS) | Meerkat Cloud |
-|--|-----------------|---------------|
-| **API** | Identical | Identical |
-| **LLM keys** | You supply (BYOK) | You supply (BYOK) |
-| **Infra / ops** | You run Postgres + workers | Managed for you |
-| **Base URL** | `http://localhost:3000/api/v1` | `https://cloud.meerkatagents.com/api/v1` (default) |
-
-LLM usage is always billed by **your provider**. Meerkat never sees your model costs.
-
-Self-host: [meerkat README — Docker](https://github.com/Tiny-Bubble-Company/meerkat#getting-started--docker-recommended)
-
----
-
-## Installation
-
-Add to your Gemfile:
-
-```ruby
-gem "meerkat-agents"
-```
-
-Or install directly:
+Change Intelligence for Ruby. Create monitors, inspect runs and artifacts, receive signed webhooks.
 
 ```bash
 gem install meerkat-agents
 ```
 
-Then in your app:
-
 ```ruby
 require "meerkat"
 ```
 
+Default API base: `https://cloud.meerkatagents.com/api/v1`
+
 ---
 
 ## Quick start
 
-### 1. Get an API key
-
-Sign up via the [Meerkat Cloud dashboard](https://cloud.meerkatagents.com/signup) or programmatically:
-
-```ruby
-require "meerkat"
+### 1. Sign up
 
-client = Meerkat::Client.new(base_url: "https://cloud.meerkatagents.com/api/v1")
-result = client.signup.create(email: "you@company.com", name: "Your Name")
-api_key = result.dig("data", "api_key") # store securely — shown once
-```
+[cloud.meerkatagents.com/signup](https://cloud.meerkatagents.com/signup) — copy `MEERKAT_API_KEY`, add your LLM key under **LLM key**.
 
-### 2. Create a task
+### 2. Create a monitor
 
 ```ruby
 client = Meerkat::Client.new(api_key: ENV["MEERKAT_API_KEY"])
 
-response = client.tasks.create(
-  task_type: "recurring",
-  description: "Monitor courier tracking and notify on status changes",
-  input_params: { courier_tracking_link: "https://..." },
-  frequency: "every 2 hours",
-  output_webhook: "https://your-app.com/webhooks/meerkat"
-)
-
-task = response["data"]
-```
-
-### 3. Trigger a run (optional)
-
-```ruby
-client.tasks.run(task["id"], async: true)
-```
-
----
-
-## Examples
-
-### List and filter tasks
-
-```ruby
-client.tasks.list(status: "active", task_type: "recurring", limit: 20)
-client.tasks.retrieve(1)
-client.tasks.pause(1)
-client.tasks.resume(1)
-client.tasks.delete(1)
-```
-
-### One-off lookup
-
-```ruby
-client.tasks.create(
-  task_type: "one_off",
-  description: "Fetch the current price of this product",
-  input_params: { url: "https://example.com/product/123" },
-  output_webhook: "https://your-app.com/webhooks/meerkat"
+client.monitors.create(
+  description: "Notify me when pricing or plan limits change",
+  input_params: { url: "https://competitor.com/pricing" },
+  frequency: "every 6 hours",
+  output_webhook: "https://myapp.com/webhooks/meerkat"
 )
 ```
 
-### Inspect runs and webhook delivery history
+All monitors are recurring. There is no `task_type`.
 
-```ruby
-client.tasks.runs(1, limit: 10)
-client.tasks.events(1, limit: 50)
-```
-
-### API keys
+### 3. List / update / delete
 
 ```ruby
-client.api_keys.list
-client.api_keys.create(name: "Production")
-client.api_keys.revoke(key_id)
+client.monitors.list
+client.monitors.retrieve(id)
+client.monitors.update(id, frequency: "every 12 hours")
+client.monitors.pause(id)
+client.monitors.resume(id)
+client.monitors.delete(id)
 ```
 
----
-
-## Receiving webhooks (Rails)
-
-Every outbound POST is HMAC-SHA256 signed in the `X-Meerkat-Signature` header. Verify before processing:
+### 4. Runs & artifacts
 
 ```ruby
-Meerkat::Webhooks.verify(
-  payload: request.raw_post,
-  signature: request.headers["X-Meerkat-Signature"],
-  secret: ENV["MEERKAT_WEBHOOK_SECRET"]
-)
+client.monitors.runs(id)
+client.monitors.retrieve_run(id, run_id)
+client.monitors.artifacts(id, run_id)  # structured findings from the run
+client.monitors.run(id)                # trigger an on-demand run
 ```
 
-### Rails controller concern
+### 5. Webhooks in Rails
 
 ```ruby
 class Webhooks::MeerkatController < ApplicationController
@@ -412,120 +63,33 @@ class Webhooks::MeerkatController < ApplicationController
 
   def create
     payload = JSON.parse(request.raw_post)
-    # handle event: run_completed, status_changed, etc.
     head :ok
   end
 end
 ```
 
-Set `MEERKAT_WEBHOOK_SECRET` in your environment.
-
----
-
-## Output formats
-
-`output_webhook` is required on every task (or use `"default"` if your account has a default webhook configured). `output_format` is optional.
-
-| Preset | Webhook payload shape |
-|--------|----------------------|
-| `default` | `{ event, task_id, task_run_id, occurred_at, data: { summary, findings, change_detected, ... } }` |
-| `compact` | Top-level `summary`, `change_detected`, `findings` |
-| `flat` | Findings merged into the webhook root object |
-| `findings_only` | Findings object only |
-| `minimal` | `event`, `task_id`, `summary`, `change_detected` |
-
-```ruby
-client.tasks.create(
-  description: "...",
-  input_params: { url: "https://..." },
-  output_webhook: "https://your-app.com/hook",
-  output_format: "flat"
-)
-```
-
-Any other string is passed to the agent as a custom instruction for shaping findings (max 500 chars).
-
----
-
-## API reference
-
-Default base URL: `https://cloud.meerkatagents.com/api/v1`
-
-All endpoints except signup require `Authorization: Bearer mk_...`.
-
-| SDK method | HTTP | Description |
-|------------|------|-------------|
-| `client.signup.create(...)` | `POST /signup` | Create account + API key |
-| `client.api_keys.list` | `GET /api_keys` | List API keys |
-| `client.api_keys.create(name:)` | `POST /api_keys` | Generate a new key |
-| `client.api_keys.revoke(id)` | `DELETE /api_keys/:id` | Revoke a key |
-| `client.tasks.list(...)` | `GET /tasks` | List tasks |
-| `client.tasks.create(...)` | `POST /tasks` | Create a task |
-| `client.tasks.retrieve(id)` | `GET /tasks/:id` | Task details + last known state |
-| `client.tasks.update(id, ...)` | `PATCH /tasks/:id` | Partial update |
-| `client.tasks.replace(id, ...)` | `PUT /tasks/:id` | Full replace |
-| `client.tasks.delete(id)` | `DELETE /tasks/:id` | Archive or delete |
-| `client.tasks.run(id, async:)` | `POST /tasks/:id/run` | Trigger on-demand run |
-| `client.tasks.pause(id)` | `POST /tasks/:id/pause` | Pause recurring task |
-| `client.tasks.resume(id)` | `POST /tasks/:id/resume` | Resume recurring task |
-| `client.tasks.runs(id)` | `GET /tasks/:id/runs` | Run history |
-| `client.tasks.events(id)` | `GET /tasks/:id/events` | Webhook delivery log |
-
-Full OpenAPI spec: [`meerkat/openapi/openapi.yaml`](https://github.com/Tiny-Bubble-Company/meerkat/blob/main/openapi/openapi.yaml)
+Set `MEERKAT_WEBHOOK_SECRET`.
 
 ---
 
 ## Configuration
 
-### Environment variables
-
 | Variable | Description |
 |----------|-------------|
-| `MEERKAT_API_KEY` | API key from signup (`mk_...`) |
-| `MEERKAT_BASE_URL` | API base URL (default: Meerkat Cloud) |
-| `MEERKAT_WEBHOOK_SECRET` | Secret for verifying inbound webhooks |
-
-### Rails / global config
-
-```ruby
-Meerkat.configure do |config|
-  config.api_key = ENV["MEERKAT_API_KEY"]
-  config.base_url = ENV.fetch("MEERKAT_BASE_URL", Meerkat::Client::DEFAULT_BASE_URL)
-end
-
-Meerkat.configuration.client.tasks.list(status: "active")
-```
-
-### Self-hosted instance
-
-```ruby
-client = Meerkat::Client.new(
-  api_key: ENV["MEERKAT_API_KEY"],
-  base_url: "http://localhost:3000/api/v1"
-)
-```
+| `MEERKAT_API_KEY` | From Cloud signup |
+| `MEERKAT_WEBHOOK_SECRET` | HMAC verification |
+| `MEERKAT_BASE_URL` | Optional; defaults to Cloud |
 
 ---
 
-## Development
-
-```bash
-bundle install
-bundle exec rake spec
-```
-
-See [PUBLISHING.md](PUBLISHING.md) for local testing and RubyGems release steps.
-
----
+## Pricing
 
-## Related projects
+Free: 1 monitor · 1 run. Then [$20 — 5 monitors, 50 runs](https://cloud.meerkatagents.com/subscribe).
 
-- [meerkat](https://github.com/Tiny-Bubble-Company/meerkat) — open source API server
-- [meerkat-python](https://github.com/Tiny-Bubble-Company/meerkat-python) — Python SDK
-- [meerkat-javascript](https://github.com/Tiny-Bubble-Company/meerkat-javascript) — JavaScript/TypeScript SDK
+Limit hit → `Meerkat::SubscriptionRequiredError`.
 
 ---
 
-## License
+## Docs
 
-MIT — see [LICENSE](LICENSE).
+https://cloud.meerkatagents.com/docs/introduction

data/lib/meerkat/client.rb

@@ -19,8 +19,13 @@ module Meerkat
       @signup ||= Resources::Signup.new(self)
     end
 
+    def monitors
+      @monitors ||= Resources::Monitors.new(self)
+    end
+
+    # Deprecated: use {#monitors}. Kept for older examples.
     def tasks
-      @tasks ||= Resources::Tasks.new(self)
+      monitors
     end
 
     def api_keys
@@ -90,6 +95,8 @@ module Meerkat
         body
       when 401
         raise AuthenticationError.new(error_detail(body), status: 401, errors: body&.dig("errors"))
+      when 402
+        raise SubscriptionRequiredError.new(error_detail(body), status: 402, errors: body&.dig("errors"))
       when 404
         raise NotFoundError.new(error_detail(body), status: 404, errors: body&.dig("errors"))
       when 422

data/lib/meerkat/error.rb

@@ -14,5 +14,6 @@ module Meerkat
   class AuthenticationError < Error; end
   class NotFoundError < Error; end
   class ValidationError < Error; end
+  class SubscriptionRequiredError < Error; end
   class ApiError < Error; end
 end

data/lib/meerkat/resources/monitors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Meerkat
+  module Resources
+    # Change Intelligence monitors — always recurring.
+    # CRUD + runs/artifacts against /api/v1/monitors.
+    class Monitors < Base
+      def list(status: nil, include_archived: nil, limit: nil, offset: nil)
+        client.get("/monitors", params: {
+          status: status,
+          include_archived: include_archived,
+          limit: limit,
+          offset: offset
+        }.compact)
+      end
+
+      def retrieve(id)
+        client.get("/monitors/#{id}")
+      end
+
+      def create(**attributes)
+        client.post("/monitors", body: { monitor: public_attrs(attributes) })
+      end
+
+      def update(id, **attributes)
+        client.patch("/monitors/#{id}", body: { monitor: public_attrs(attributes) })
+      end
+
+      def replace(id, **attributes)
+        client.put("/monitors/#{id}", body: { monitor: public_attrs(attributes) })
+      end
+
+      def delete(id, permanent: false)
+        client.delete("/monitors/#{id}", params: { permanent: permanent })
+      end
+
+      def run(id, async: true)
+        client.post("/monitors/#{id}/run", params: { async: async })
+      end
+
+      def pause(id)
+        client.post("/monitors/#{id}/pause")
+      end
+
+      def resume(id)
+        client.post("/monitors/#{id}/resume")
+      end
+
+      def runs(id, limit: nil)
+        client.get("/monitors/#{id}/runs", params: { limit: limit }.compact)
+      end
+
+      def retrieve_run(id, run_id)
+        client.get("/monitors/#{id}/runs/#{run_id}")
+      end
+
+      def artifacts(id, run_id)
+        client.get("/monitors/#{id}/runs/#{run_id}/artifacts")
+      end
+
+      def events(id, limit: nil)
+        client.get("/monitors/#{id}/events", params: { limit: limit }.compact)
+      end
+
+      private
+
+      def public_attrs(attributes)
+        attributes = attributes.transform_keys(&:to_sym)
+        attributes.delete(:task_type)
+        attributes
+      end
+    end
+  end
+end

data/lib/meerkat/resources/signup.rb

@@ -3,12 +3,13 @@
 module Meerkat
   module Resources
     class Signup < Base
-      def create(email:, name: nil, company: nil)
+      def create(email:, company:, website:, name: nil)
         client.post("/signup", body: {
           customer: {
             email: email,
             name: name,
-            company: company
+            company: company,
+            website: website
           }.compact
         })
       end

data/lib/meerkat/resources/tasks.rb

@@ -2,55 +2,12 @@
 
 module Meerkat
   module Resources
-    class Tasks < Base
-      def list(task_type: nil, status: nil, include_archived: nil, limit: nil, offset: nil)
-        client.get("/tasks", params: {
-          task_type: task_type,
-          status: status,
-          include_archived: include_archived,
-          limit: limit,
-          offset: offset
-        }.compact)
-      end
-
-      def retrieve(id)
-        client.get("/tasks/#{id}")
-      end
-
+    # @deprecated Use {Monitors} (`client.monitors`) instead.
+    # Delegates to the monitors API for backward compatibility.
+    class Tasks < Monitors
       def create(**attributes)
-        client.post("/tasks", body: { task: attributes })
-      end
-
-      def update(id, **attributes)
-        client.patch("/tasks/#{id}", body: { task: attributes })
-      end
-
-      def replace(id, **attributes)
-        client.put("/tasks/#{id}", body: { task: attributes })
-      end
-
-      def delete(id, permanent: false)
-        client.delete("/tasks/#{id}", params: { permanent: permanent })
-      end
-
-      def run(id, async: true)
-        client.post("/tasks/#{id}/run", params: { async: async })
-      end
-
-      def pause(id)
-        client.post("/tasks/#{id}/pause")
-      end
-
-      def resume(id)
-        client.post("/tasks/#{id}/resume")
-      end
-
-      def runs(id, limit: nil)
-        client.get("/tasks/#{id}/runs", params: { limit: limit }.compact)
-      end
-
-      def events(id, limit: nil)
-        client.get("/tasks/#{id}/events", params: { limit: limit }.compact)
+        # Old clients may still send task_type — strip and route to monitors.
+        super(**attributes)
       end
     end
   end

data/lib/meerkat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Meerkat
-  VERSION = "0.1.1"
+  VERSION = "0.3.1"
 end

data/lib/meerkat.rb

@@ -8,6 +8,7 @@ require_relative "meerkat/configuration"
 require_relative "meerkat/resources/base"
 require_relative "meerkat/resources/signup"
 require_relative "meerkat/resources/api_keys"
+require_relative "meerkat/resources/monitors"
 require_relative "meerkat/resources/tasks"
 
 if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meerkat-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Tiny Bubble Company
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-28 00:00:00.000000000 Z
+date: 2026-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -31,13 +31,36 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3'
 description: |
-  Meerkat is an open-source, webhook-native API for async agent tasks. Run background work similar to
-  Sidekiq — register a job and walk away — but describe the task in plain English and Meerkat understands
-  what to do and acts accordingly (fetch pages, extract data, compare state, retry on failure). Monitor
-  any website for changes, track shipments, watch competitor prices and stock, or schedule recurring
-  scraping jobs — and get an HMAC-signed webhook when something happens. Bring your own LLM key
-  (OpenAI, Anthropic, OpenRouter, Grok, or open-source models via compatible providers) — no schedulers
-  or webhook plumbing to build yourself.
+  Meerkat Agents is the official Ruby client for Meerkat Cloud Change Intelligence.
+
+  Problem it solves
+  -----------------
+  Rails apps often need to know when something on the web changes — competitor pricing,
+  plan pages, package tracking, stock, or content — without building scrapers, cron jobs,
+  HTML diffs, retries, and webhook plumbing. Meerkat runs that watch loop in the cloud and
+  POSTs structured change events to your Rails app.
+
+  How it differs from Sidekiq / Active Job / Good Job / Solid Queue / Delayed Job / Resque
+  ----------------------------------------------------------------------------------------
+  Those gems are excellent for running YOUR Ruby jobs on YOUR workers (background jobs,
+  queues, cron). Meerkat is not a job queue. You describe what to watch in plain English;
+  Meerkat fetches sources, uses your LLM key (BYOK) to judge meaningful change, and delivers
+  signed JSON webhooks. No Sidekiq workers or scraping code required for the monitoring path.
+
+  Common use cases
+  ----------------
+  - Website / page change monitoring
+  - Competitor price and plan monitoring
+  - Package / shipment tracking alerts
+  - Stock and availability watches
+  - Recurring web scraping with structured findings
+  - Change detection webhooks for Rails and API backends
+
+  Keywords: rails, ruby, sidekiq, activejob, background jobs, webhook, web scraping,
+  website monitoring, price monitoring, package tracking, cron, scheduler, llm, agents,
+  change detection, faraday.
+
+  Docs: https://cloud.meerkatagents.com/docs/introduction
 email:
 - hello@meerkatagents.com
 executables: []
@@ -57,16 +80,20 @@ files:
 - lib/meerkat/railtie.rb
 - lib/meerkat/resources/api_keys.rb
 - lib/meerkat/resources/base.rb
+- lib/meerkat/resources/monitors.rb
 - lib/meerkat/resources/signup.rb
 - lib/meerkat/resources/tasks.rb
 - lib/meerkat/version.rb
 - lib/meerkat/webhooks.rb
-homepage: https://github.com/Tiny-Bubble-Company/meerkat-ruby
+homepage: https://cloud.meerkatagents.com/docs/introduction
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://cloud.meerkatagents.com/docs/introduction
+  documentation_uri: https://cloud.meerkatagents.com/docs/introduction
   source_code_uri: https://github.com/Tiny-Bubble-Company/meerkat-ruby
   changelog_uri: https://github.com/Tiny-Bubble-Company/meerkat-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Tiny-Bubble-Company/meerkat-ruby/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -86,6 +113,6 @@ requirements: []
 rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
-summary: Async agent task API — monitor websites for changes, track deliveries, watch
-  prices/stock via webhooks.
+summary: Change Intelligence for Rails — website monitoring, price tracking, webhooks
+  (not Sidekiq).
 test_files: []