meerkat-agents 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0270f21d356660800f70b0e6e47a6c47bbd8978533748d150e9e7145d3ed8dbb
+  data.tar.gz: 37afac9bf07c8bc93bb51e43a31fd2968c09742ccfbac506df3cae5a1f00eeb7
+SHA512:
+  metadata.gz: 6dda18ade21f2a9d99b49ebb30a64dbd4610012d40362f78469bbb2e9b269982f8b333a64068537e0c4321f5bcc79cc8133e13b9091bffbec4bfed7359854d5d
+  data.tar.gz: 85640b0912fb3730bbbb24541c60b8aa4be13877250cc018661e968e68d8f12f59e0d1606383ab4fcb3f27a18d6cb75377910f7f9efe1e8d88254755c7446c69

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+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.1.0] - 2026-06-27
+
+### Added
+
+- Initial release of the Meerkat Ruby client (`meerkat-agents` on RubyGems, `require "meerkat"`)
+- Task, signup, and API key resources
+- Webhook HMAC-SHA256 verification helpers
+- Optional Rails railtie and webhook verification concern
+
+[0.1.0]: https://github.com/Tiny-Bubble-Company/meerkat-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiny Bubble Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,531 @@
+<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:
+
+```bash
+gem install meerkat-agents
+```
+
+Then in your app:
+
+```ruby
+require "meerkat"
+```
+
+---
+
+## Quick start
+
+### 1. Get an API key
+
+Sign up via the [Meerkat Cloud dashboard](https://cloud.meerkatagents.com/signup) or programmatically:
+
+```ruby
+require "meerkat"
+
+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
+```
+
+### 2. Create a task
+
+```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"
+)
+```
+
+### Inspect runs and webhook delivery history
+
+```ruby
+client.tasks.runs(1, limit: 10)
+client.tasks.events(1, limit: 50)
+```
+
+### API keys
+
+```ruby
+client.api_keys.list
+client.api_keys.create(name: "Production")
+client.api_keys.revoke(key_id)
+```
+
+---
+
+## Receiving webhooks (Rails)
+
+Every outbound POST is HMAC-SHA256 signed in the `X-Meerkat-Signature` header. Verify before processing:
+
+```ruby
+Meerkat::Webhooks.verify(
+  payload: request.raw_post,
+  signature: request.headers["X-Meerkat-Signature"],
+  secret: ENV["MEERKAT_WEBHOOK_SECRET"]
+)
+```
+
+### Rails controller concern
+
+```ruby
+class Webhooks::MeerkatController < ApplicationController
+  include Meerkat::Rails::WebhookVerification
+
+  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)
+
+---
+
+## 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"
+)
+```
+
+---
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+See [PUBLISHING.md](PUBLISHING.md) for local testing and RubyGems release steps.
+
+---
+
+## Related projects
+
+- [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
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/meerkat/client.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module Meerkat
+  class Client
+    DEFAULT_BASE_URL = "https://cloud.meerkatagents.com/api/v1"
+    USER_AGENT = "meerkat-agents/#{Meerkat::VERSION}"
+
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: 30, faraday: nil)
+      @api_key = api_key
+      @base_url = normalize_base_url(base_url)
+      @timeout = timeout
+      @connection = faraday || build_connection
+    end
+
+    def signup
+      @signup ||= Resources::Signup.new(self)
+    end
+
+    def tasks
+      @tasks ||= Resources::Tasks.new(self)
+    end
+
+    def api_keys
+      @api_keys ||= Resources::ApiKeys.new(self)
+    end
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body: nil, params: {})
+      request(:post, path, body: body, params: params)
+    end
+
+    def patch(path, body: nil)
+      request(:patch, path, body: body)
+    end
+
+    def put(path, body: nil)
+      request(:put, path, body: body)
+    end
+
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    private
+
+    attr_reader :api_key, :connection
+
+    def build_connection
+      Faraday.new(url: @base_url) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/, parser_options: { symbolize_names: false }
+        f.options.timeout = @timeout
+        f.options.open_timeout = 10
+        f.headers["User-Agent"] = USER_AGENT
+        f.headers["Accept"] = "application/json"
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def normalize_base_url(base_url)
+      "#{base_url.to_s.chomp("/")}/"
+    end
+
+    def request(method, path, body: nil, params: {})
+      relative_path = path.start_with?("/") ? path[1..] : path
+
+      response = connection.public_send(method, relative_path) do |req|
+        req.headers["Authorization"] = "Bearer #{api_key}" if api_key
+        req.params.update(params) if params.any?
+        req.body = body if body
+      end
+
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      return nil if response.status == 204
+
+      body = response.body
+      body = JSON.parse(body) if body.is_a?(String) && !body.empty?
+
+      case response.status
+      when 200, 201, 202
+        body
+      when 401
+        raise AuthenticationError.new(error_detail(body), status: 401, errors: body&.dig("errors"))
+      when 404
+        raise NotFoundError.new(error_detail(body), status: 404, errors: body&.dig("errors"))
+      when 422
+        raise ValidationError.new(error_detail(body), status: 422, errors: body&.dig("errors"))
+      else
+        raise ApiError.new(error_detail(body), status: response.status, errors: body&.dig("errors"))
+      end
+    end
+
+    def error_detail(body)
+      return "Request failed" unless body.is_a?(Hash)
+
+      body.dig("errors", 0, "detail") || body.dig("errors", 0, "title") || "Request failed"
+    end
+  end
+end

data/lib/meerkat/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Meerkat
+  class << self
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+
+  class Configuration
+    attr_accessor :api_key, :base_url
+
+    def initialize
+      @api_key = ENV["MEERKAT_API_KEY"]
+      @base_url = ENV.fetch("MEERKAT_BASE_URL", Client::DEFAULT_BASE_URL)
+    end
+
+    def client
+      Client.new(api_key: api_key, base_url: base_url)
+    end
+  end
+end

data/lib/meerkat/error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Meerkat
+  class Error < StandardError
+    attr_reader :status, :errors
+
+    def initialize(message = nil, status: nil, errors: nil)
+      super(message)
+      @status = status
+      @errors = errors
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class ValidationError < Error; end
+  class ApiError < Error; end
+end

data/lib/meerkat/rails/webhook_verification.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "meerkat/webhooks"
+
+module Meerkat
+  module Rails
+    module WebhookVerification
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :verify_meerkat_webhook!, only: [ :create ]
+      end
+
+      private
+
+      def verify_meerkat_webhook!
+        secret = meerkat_webhook_secret
+        return if secret.blank?
+
+        signature = request.headers[Webhooks::SIGNATURE_HEADER]
+        unless Webhooks.verify(payload: request.raw_post, signature: signature, secret: secret)
+          head :unauthorized
+        end
+      end
+
+      def meerkat_webhook_secret
+        ENV["MEERKAT_WEBHOOK_SECRET"]
+      end
+    end
+  end
+end

data/lib/meerkat/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Meerkat
+  class Railtie < ::Rails::Railtie
+    initializer "meerkat.configure" do
+      Meerkat.configure
+    end
+  end
+end

data/lib/meerkat/resources/api_keys.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Meerkat
+  module Resources
+    class ApiKeys < Base
+      def list
+        client.get("/api_keys")
+      end
+
+      def create(name: "Default")
+        client.post("/api_keys", body: { api_key: { name: name } })
+      end
+
+      def revoke(id)
+        client.delete("/api_keys/#{id}")
+      end
+    end
+  end
+end

data/lib/meerkat/resources/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Meerkat
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+    end
+  end
+end

data/lib/meerkat/resources/signup.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Meerkat
+  module Resources
+    class Signup < Base
+      def create(email:, name: nil, company: nil)
+        client.post("/signup", body: {
+          customer: {
+            email: email,
+            name: name,
+            company: company
+          }.compact
+        })
+      end
+    end
+  end
+end

data/lib/meerkat/resources/tasks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+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
+
+      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)
+      end
+    end
+  end
+end

data/lib/meerkat/version.rb

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

data/lib/meerkat/webhooks.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Meerkat
+  module Webhooks
+    SIGNATURE_HEADER = "X-Meerkat-Signature"
+    EVENT_HEADER = "X-Meerkat-Event"
+
+    module_function
+
+    def sign(payload:, secret:)
+      digest = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+      "sha256=#{digest}"
+    end
+
+    def verify(payload:, signature:, secret:)
+      return false if signature.nil? || signature.empty?
+
+      expected = sign(payload: payload, secret: secret)
+      secure_compare(signature, expected)
+    end
+
+    def secure_compare(provided, expected)
+      return false unless provided.bytesize == expected.bytesize
+
+      result = 0
+      provided.bytes.zip(expected.bytes) { |a, b| result |= a ^ b }
+      result.zero?
+    end
+    private_class_method :secure_compare
+  end
+end

data/lib/meerkat.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "meerkat/version"
+require_relative "meerkat/error"
+require_relative "meerkat/webhooks"
+require_relative "meerkat/client"
+require_relative "meerkat/configuration"
+require_relative "meerkat/resources/base"
+require_relative "meerkat/resources/signup"
+require_relative "meerkat/resources/api_keys"
+require_relative "meerkat/resources/tasks"
+
+if defined?(Rails::Railtie)
+  require_relative "meerkat/railtie"
+  require_relative "meerkat/rails/webhook_verification"
+end
+
+module Meerkat
+  class << self
+    def client(**options)
+      Client.new(**options)
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: meerkat-agents
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tiny Bubble Company
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: |
+  Meerkat is an open-source, webhook-native API for async agent tasks. 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. BYOK, no schedulers or webhook plumbing to build yourself.
+email:
+- hello@meerkatagents.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/meerkat-logo.png"
+- ".github/readme-banner.png"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/meerkat.rb
+- lib/meerkat/client.rb
+- lib/meerkat/configuration.rb
+- lib/meerkat/error.rb
+- lib/meerkat/rails/webhook_verification.rb
+- lib/meerkat/railtie.rb
+- lib/meerkat/resources/api_keys.rb
+- lib/meerkat/resources/base.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
+licenses:
+- MIT
+metadata:
+  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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+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.
+test_files: []