busybee 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c005e2f714f3f1ea1b3eedf3d8e7b6ce72ad88fe27cf2a8e84637ca4fe3de281
-  data.tar.gz: cbefb422a412d32143493b8903886e6429f59bd639a3a05de052f89a94be9edb
+  metadata.gz: a3bba732da4bc16cfdcf50a8ad7815d8c5dd45d7ae71d5e2978ebe7ba357d1f9
+  data.tar.gz: 33cf8753e76eedc975b779185fd38134597a198ef4c8522b090fcfb4d600d390
 SHA512:
-  metadata.gz: e812d00b20c0ff7395b72db6225d57a2adcdee6ad9ecf7381215cd5352b5b034458df6bb3728a3cd25429effee83bc1f85c941dc2f4a7937f86cfb3d64f21688
-  data.tar.gz: 61a813477c650a801a04d6d5ed50dc2a5bbef5686de5690599943a61898d2b77a3d66c52109c037c4e99fcf0cfb02c2393cb9f369cac9a65d3ef9da20a8d9da2
+  metadata.gz: 5d068b139505b17f1b91cfdd86c53420c284133507e0dd3263a00236708abb261b0b2318524bbff816cbbf9407961d00610a8d35dab438f7a7b268ade9595f39
+  data.tar.gz: aeb232681e9084912c491e3baee068b189975822eead0bfeaaa8907ed1ca72325db699c84d69fc523495a652a604cfe5a836d86571badc83274a91e00b5259ad

data/CHANGELOG.md

@@ -1,12 +1,74 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-12-29
+## v0.3.0 (2026-03-13)
+
+Worker Pattern Framework and CLI, with testing helpers and YAML configuration support.
+
+### New Features:
+
+- **Worker Pattern** (`Busybee::Worker`) – Define job handlers as Ruby classes with a clean DSL:
+  - Declarative inputs (`variable`, `header`) and outputs with type hints, defaults, and validation
+  - Accessor methods for inputs – use `order_id` directly in `perform` instead of `variables[:order_id]`
+  - Automatic job completion on success and failure reporting on exception (`complete_job_on_success`, `fail_job_on_error`)
+  - Manual lifecycle control via `complete!`, `fail!`, `throw_bpmn_error!` for complex flows
+  - Configurable `shutdown_on` for exceptions that should trigger graceful process shutdown (e.g., `PG::ConnectionBad`)
+  - Per-worker configuration via DSL (`worker_mode`, `polling`, `streaming`, `job_timeout`, `backoff`, `backpressure_delay`)
+
+- **CLI** (`bundle exec busybee`) – Run workers as long-lived processes:
+  - Positional args: `busybee Worker1 Worker2 Worker3`
+  - YAML config: `busybee --config config/busybee.yml`
+  - Flags: `--worker-mode`, `--log-format`, `--worker-name`, `--cluster-address`
+  - Automatic Rails environment loading (skip with `BUSYBEE_SKIP_RAILS=1`)
+  - Graceful shutdown on INT/TERM/QUIT; force shutdown on second signal
+
+- **Three Worker Modes:**
+  - **Polling** – long-polls the Zeebe gateway for available jobs
+  - **Streaming** – persistent gRPC stream for lowest-latency job delivery, with optional in-memory buffer and throttle
+  - **Hybrid** (default) – combines streaming with polling to handle both new jobs and pre-existing backlogs while still guaranteeing sequential execution
+
+- **Multiple Workers:** – run multiple worker classes in a single process, each in its own thread with independently-resolved configuration
+
+- **YAML Configuration** – define workers and per-worker configuration in a config file. Top-level settings apply to all workers; per-worker overrides take precedence
+
+- **Worker Testing Helpers:**
+  - `execute_worker(WorkerClass, variables: {...})` – run a worker's full lifecycle against a test job without Zeebe
+  - `build_test_job(variables: {...})` – construct a test job backed by a stub client for state inspection
+  - RSpec matchers: `complete_job(job)`, `fail_job(job)`, `throw_bpmn_error_on(job)` with chainable assertions (`.with_vars`, `.with_error`, `.with_code`)
+
+## v0.2.0 (2026-02-05)
+
+Production-ready Client API with Rails integration.
+
+### New Features:
+
+- **Client Class** (`Busybee::Client`) - a Ruby-idiomatic wrapper around the Zeebe gRPC API:
+  - Pluggable authentication with four credential types: `Insecure`, `TLS`, `OAuth`, and `CamundaCloud`
+    - Automatic credential type detection from parameters
+  - Almost all GRPC operations, including `deploy_process`, `start_instance`, `cancel_instance`, `publish_message`, `broadcast_signal` `set_variables`, `resolve_incident`, `complete_job`, `fail_job`, `throw_bpmn_error`, `update_job_retries`, `update_job_timeout`
+  - Two job activation methods: `with_each_job` (long-polling), and `open_job_stream` (continuous stream) with Enumerable wrapper class
+  - Rich wrapper class (`Busybee::Job`) for activated jobs:
+    - `variables` and `headers` with indifferent access (string or symbol keys)
+    - Status tracking (`:ready`, `:complete`, `:failed`) to prevent double-completion
+    - Action methods: `complete!`, `fail!`, `throw_bpmn_error!`
+  - Variable serialization handles ActiveRecord or other custom objects
+
+- **Rails Integration** - Automatic configuration from `config.x.busybee.*`, works seamlessly with Rails secrets
+  - Defaults to using Rails logger
+  - Structured logs with a `[busybee]` prefix, supporting text or JSON modes
+
+### Breaking Changes:
+
+- **Testing::Helpers:**
+  - Now uses `Busybee.cluster_address` instead of `Busybee::Testing.address`, which has been removed
+  - Was refactored for namespace safety and some methods are no longer accessible within specs
+
+## v0.1.0 (2025-12-29)
 
 Initial public release with foundational components for testing BPMN workflows.
 
-### Added
+### New Features:
 
-- **Testing module** (`Busybee::Testing`) - RSpec helpers and matchers for testing BPMN workflows against Zeebe:
+- **Testing Module** (`Busybee::Testing`) - RSpec helpers and matchers for testing BPMN workflows against Zeebe:
   - `deploy_process` - Deploy BPMN files with optional unique IDs for test isolation
   - `with_process_instance` - Create process instances with automatic cleanup
   - `activate_job` / `activate_jobs` - Activate jobs for assertions
@@ -16,8 +78,10 @@ Initial public release with foundational components for testing BPMN workflows.
   - `ActivatedJob` fluent API with `expect_variables`, `expect_headers`, `and_complete`, `and_fail`, `and_throw_error_event`
   - RSpec matchers: `have_activated`, `have_received_variables`, `have_received_headers`
 
-- **GRPC layer** (`Busybee::GRPC`) - Generated protocol buffer classes from the Zeebe 8.8 proto definition for direct Zeebe API access
+- **GRPC Layer** (`Busybee::GRPC`) - Generated protocol buffer classes from the Zeebe 8.8 proto definition for direct Zeebe API access
+
+## v0.0.1 (2025-12-03)
+
+- Initial development, not released
 
-## [0.0.1] - 2025-12-03
 
-- Initial development, not for release

data/README.md

@@ -2,9 +2,9 @@
 
 **A complete Ruby toolkit for workflow-based orchestration with BPMN, running on Camunda Platform.**
 
-If you're a Ruby shop that needs workflow orchestration, you've probably noticed the gap: Camunda Platform is powerful, but the Ruby ecosystem support is thin. Busybee fills that gap. One gem, one Camunda Cloud account, and you're ready to start building. And when you're ready to scale further, Busybee is ready to grow with you, with battle-proven patterns for large distributed systems.
+If you're a Ruby shop considering workflow orchestration, you might have noticed: Camunda Platform is powerful, but the Ruby ecosystem support is thin. Busybee fills that gap. One gem, one Camunda Cloud account, and you're ready to start building. And when you're ready to scale further, Busybee is ready to grow with you, with battle-proven patterns for large distributed systems.
 
-Busybee provides everything you need to work with Camunda Platform or self-hosted Zeebe from Ruby:
+Busybee provides everything you need to work with Camunda Platform or self-hosted Zeebe in a Ruby world:
 
 - **Worker Pattern Framework** - Define job handlers as classes with a clean DSL. Busybee handles polling, execution, and lifecycle.
 - **Idiomatic Zeebe Client** - Ruby-native interface with keyword arguments, sensible defaults, and proper exception handling.
@@ -17,10 +17,10 @@ Busybee provides everything you need to work with Camunda Platform or self-hoste
 | Version | Features | Status |
 |---------|---------|--------|
 | v0.1 | BPMN Testing Tools, GRPC Layer | Available now! |
-| v0.2 | Client, Rails Integration | January 2026 |
-| v0.3 | Worker Pattern & CLI | Early 2026 |
-| v0.4 | Instrumentation Hooks, Deployment Tools | Planned for Early 2026 |
-| v1.0 | Production Polish | Planned for Mid 2026 |
+| v0.2 | Client, Rails Integration | Available now! |
+| v0.3 | Worker Pattern & CLI | Available now! |
+| v0.4 | Instrumentation Hooks, Deployment Tools | Mid 2026 |
+| v1.0 | Production Polish | Late 2026 |
 
 ## Installation
 
@@ -44,50 +44,63 @@ gem install busybee
 
 ## Usage
 
-### Worker Pattern Framework (coming in early 2026)
+### Worker Pattern Framework (available now!)
 
-Define job handlers as Ruby classes. Busybee manages the process lifecycle, the connection to Camunda Cloud, and requesting jobs from Zeebe. If you've used Racecar to build Kafka handlers, or Sidekiq to build background jobs, this should feel very familiar.
-
-> This feature is still being designed. The example shown here is only representative and will change before implementation.
+Define job handlers as Ruby classes. Busybee manages the process lifecycle, the connection to Camunda Cloud, and requesting jobs from Zeebe. If you've used Sidekiq to build background jobs, this should feel very familiar.
 
 ```ruby
 class ProcessOrderWorker < Busybee::Worker
-  type "process-order"
+  job_type "process_order"
 
-  input :order_id, required: true
-  input :customer_email
+  variable :order_id, type: :uuid
+  variable :customer_email, required: false
 
-  output :confirmation_number
+  output :confirmation_number, type: :string
 
   def perform
-    confirmation = OrderService.process(order_id)
-    complete(confirmation_number: confirmation)
+    order = Order.find(order_id)
+    confirmation = order.process!
+    EmailService.send_confirmation(customer_email, confirmation) if customer_email
+    { confirmation_number: confirmation }
   end
 end
 ```
 
-Planned capabilities:
+Run workers from the command line:
 
-- Declarative input/output definitions with validation
-- Automatic job activation and completion
-- Configurable timeouts and retry behavior
-- Graceful shutdown on SIGTERM
-- CLI for running workers: `bundle exec busybee work` or similar
+```bash
+bundle exec busybee ProcessOrderWorker ShipOrderWorker
 
-### Idiomatic Zeebe Client (coming in January 2026)
+# Or with a YAML config file
+bundle exec busybee --config config/busybee.yml
+```
 
-A Ruby-native client for Zeebe with keyword arguments, sensible defaults, and proper exception handling.
+Capabilities:
+
+- Declarative input/output definitions with validation and accessor methods
+- Automatic job completion and failure reporting
+- Three worker modes (polling, streaming, hybrid) for different workload patterns
+- Configurable timeouts, retry backoff, and backpressure handling
+- Graceful shutdown on SIGTERM/SIGINT
+- YAML configuration with per-worker overrides
+- RSpec matchers for unit testing workers without Zeebe
+
+**[Full worker documentation &rarr;](docs/workers.md)**
+
+### Idiomatic Zeebe Client (available now!)
 
-> This feature is still being designed. The example shown here is only representative and will change before implementation.
+A Ruby-native client for Zeebe with keyword arguments, sensible defaults, and proper exception handling.
 
 ```ruby
+# Connect to Camunda Cloud with environment variables
+# (CAMUNDA_CLIENT_ID, CAMUNDA_CLIENT_SECRET, CAMUNDA_CLUSTER_ID, CAMUNDA_CLUSTER_REGION)
 client = Busybee::Client.new
 
 # Deploy a workflow
 client.deploy_process("workflows/order-fulfillment.bpmn")
 
 # Start a process instance
-instance_key = client.start_process("order-fulfillment",
+instance_key = client.start_instance("order-fulfillment",
   vars: { order_id: "123", items: ["widget", "gadget"] }
 )
 
@@ -96,19 +109,27 @@ client.publish_message("payment-received",
   correlation_key: "order-123",
   vars: { amount: 99.99 }
 )
+
+# Process jobs (for ad-hoc use; for production job processing, use the Worker pattern above)
+client.with_each_job("send-confirmation") do |job|
+  EmailService.send(job.variables.customer_email)
+  job.complete!(sent_at: Time.now.iso8601)
+end
 ```
 
-Planned capabilities:
+Capabilities:
+
+- Multiple credential types (Insecure, TLS, OAuth, Camunda Cloud) with automatic detection
+- Complete process lifecycle: deploy, start, cancel, set variables, resolve incidents
+- Job operations: activate, complete, fail, throw BPMN errors, streaming
+- Rails integration via Railtie with `config.x.busybee.*` configuration
+- GRPC error wrapping with configurable retry
 
-- Connection management with automatic reconnection
-- Multiple credential types (insecure, TLS, OAuth, Camunda Cloud)
-- GRPC error wrapping with preserved cause chains
-- Rails integration via Railtie and `config/busybee.yml`
-- Duration support for timeouts (works with ActiveSupport if present)
+**[Full client documentation →](docs/client.md)**
 
 ### RSpec Testing Integration (available now!)
 
-Deploy processes, create instances, activate jobs, and verify workflow behavior against a real Zeebe instance. A full replacement for the [zeebe_bpmn_rspec](https://github.com/ezcater/zeebe_bpmn_rspec) gem.
+Allows you to unit test your BPMN files. Deploy processes, create instances, activate jobs, and verify workflow behavior against a real Zeebe instance.
 
 #### Setup
 
@@ -117,8 +138,9 @@ Deploy processes, create instances, activate jobs, and verify workflow behavior
 require "rspec"
 require "busybee/testing"
 
-Busybee::Testing.configure do |config|
-  config.address = "localhost:26500"  # or use ZEEBE_ADDRESS env var
+# Optional: defaults to localhost:26500, or set CLUSTER_ADDRESS env var
+Busybee.configure do |config|
+  config.cluster_address = "localhost:26500"
 end
 ```
 
@@ -156,9 +178,9 @@ end
 - `assert_process_completed!` - Verify workflow reached an end event
 - `have_activated`, `have_received_variables`, `have_received_headers` - RSpec matchers
 
-**[Full testing documentation](docs/testing.md)**
+**For more info, see our [full testing documentation here](docs/testing.md).** For unit testing workers, see [Workers: Testing Workers](docs/workers.md#testing-workers).
 
-### Deployment Tools (coming in early 2026)
+### Deployment Tools (coming in mid 2026)
 
 CI/CD tooling for deploying BPMN processes to your Zeebe clusters. Version tracking, environment-specific deployments, and pre-deployment validation.
 
@@ -166,6 +188,8 @@ CI/CD tooling for deploying BPMN processes to your Zeebe clusters. Version track
 
 For edge cases where the higher-level abstractions don't cover what you need, busybee exposes the raw GRPC interface to Zeebe. This is a complete drop-in replacement for the now-discontinued [zeebe-client](https://github.com/zeebe-io/zeebe-client-ruby) gem.
 
+> Most users won't need this, as the Testing module, Client class, and Worker pattern cover most common use cases.
+
 ```ruby
 require "busybee/grpc"
 
@@ -179,17 +203,21 @@ response = stub.topology(request)
 puts response.brokers.map(&:host)
 ```
 
-Most users won't need this—the Testing module and future Client cover common workflows. See **[GRPC documentation](docs/grpc.md)** for details.
+**For more info, see the [full GRPC documentation here](docs/grpc.md).**
+
+### Demo Application
+
+The [Dropship Co. demo app](spec/demo/README.md) is a multi-domain Rails application that showcases busybee in action. It orchestrates order fulfillment across warehousing, logistics, and delivery services using BPMN workflows and busybee workers. It's a good place to see realistic usage patterns and to experiment with the framework.
 
 ## Ruby Implementation Support
 
-Busybee currently only supports MRI (CRuby). JRuby is not supported because it cannot run C extensions (it would require `grpc-java` with a Ruby wrapper). TruffleRuby's C extension support is experimental and the `grpc` gem does not currently build on it.
+Busybee currently only supports MRI (CRuby). This is due to the state of `grpc` support on other implementations. JRuby is not supported because it cannot run C extensions (it would require `grpc-java` with a Ruby wrapper). TruffleRuby's C extension support is experimental and the `grpc` gem does not currently build on it.
 
-If you successfully run busybee on an alternative Ruby implementation, please open an issue. We'd welcome contributions to expand platform support!
+If you successfully run busybee on an alternative Ruby implementation, please open a GitHub issue to let us know! We'd welcome contributions to expand platform support.
 
 ## Development
 
-Busybee includes a Docker Compose setup for running Zeebe locally, plus rake tasks for common development workflows.
+Busybee includes a Docker Compose setup for running Zeebe locally, plus rake tasks for common development workflows:
 
 ```bash
 bin/setup              # Install dependencies
@@ -199,7 +227,7 @@ bundle exec rspec      # Run unit tests
 RUN_INTEGRATION_TESTS=1 bundle exec rspec  # Run all tests including integration
 ```
 
-**[Full development guide](docs/development.md)** — Local environment setup, running tests, regenerating GRPC classes, and release procedures.
+**The full development guide for contributors [is available here](docs/development.md),** including local environment setup, running tests, regenerating GRPC classes, and release procedures.
 
 ## Contributing
 

data/docs/client/quick_start.md

@@ -0,0 +1,279 @@
+# Busybee::Client Quick Start
+
+This tutorial gets you from zero to a deployed process and running instance in about 10 minutes. By the end, you'll have:
+
+1. A Zeebe environment (local or Camunda Cloud)
+2. Busybee configured with appropriate credentials
+3. A BPMN process deployed
+4. A running process instance
+
+## Prerequisites
+
+Before starting, you'll need:
+
+- Ruby 3.2+
+- A Zeebe environment (see "Choose Your Environment" below)
+- A BPMN process file (we'll create a simple one, or you can use an existing one)
+
+## Step 1: Install Busybee
+
+Add to your Gemfile:
+
+```ruby
+gem "busybee"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Step 2: Choose Your Environment
+
+Busybee supports both local Zeebe (typical for development) and Camunda Cloud (recommended for production).
+
+### Option A: Local Zeebe
+
+For local development, you can run Zeebe using Docker. The simplest setup is:
+
+```bash
+docker run -d --name zeebe -p 26500:26500 camunda/zeebe:latest
+```
+
+For a more complete setup with Operate (the web UI for monitoring workflows), see the [Camunda Docker Compose documentation](https://docs.camunda.io/docs/self-managed/setup/deploy/local/docker-compose/).
+
+When using local Zeebe, you'll use insecure (non-TLS) connections.
+
+### Option B: Camunda Cloud
+
+Camunda Cloud is Camunda's managed SaaS offering. To get started:
+
+1. Create a free account at [camunda.io](https://camunda.io/)
+2. Create a cluster (the free tier includes a development cluster)
+3. Create API credentials:
+   - Go to your cluster's "API" tab
+   - Click "Create new client"
+   - Select "Zeebe" scope
+   - Save the credentials (you'll need: Client ID, Client Secret, Cluster ID, and Region)
+
+For detailed setup instructions, see [Camunda Cloud Getting Started](https://docs.camunda.io/docs/guides/getting-started/).
+
+## Step 3: Configure Credentials
+
+A Busybee::Client needs to know where to find the Zeebe cluster and how to authenticate to it. There are many ways to provide or configure this information, which you can find in the [Client reference](../client.md). For the purpose of this tutorial, we'll pass this information directly to `new`:
+
+### For Local Zeebe
+
+```ruby
+require "busybee"
+
+client = Busybee::Client.new(
+  cluster_address: "localhost:26500",
+  insecure: true
+)
+```
+
+### For Camunda Cloud
+
+```ruby
+require "busybee"
+
+client = Busybee::Client.new(
+  client_id: "your client ID",
+  client_secret: "your client secret",
+  cluster_id: "your cluster ID (typically a UUID)",
+  region: "your cluster region (e.g. 'bru-2')"
+)
+```
+
+### Rails Configuration
+
+In a Rails app, configure via `config/application.rb` or an initializer:
+
+```ruby
+# config/application.rb or config/initializers/busybee.rb
+Rails.application.configure do
+  config.x.busybee.credential_type = :camunda_cloud
+  config.x.busybee.cluster_address = ENV["CLUSTER_ADDRESS"]  # for local/TLS
+  # OAuth credentials are passed to Client.new, not configured globally
+end
+```
+
+## Step 4: Create a BPMN Process
+
+BPMN (Business Process Model and Notation) files define your workflows. You can create them using:
+
+- **Camunda Modeler** (desktop app) - Download from [camunda.com/download/modeler](https://camunda.com/download/modeler/)
+- **Camunda Cloud Web Modeler** - Available in your Camunda Cloud console
+- **Any BPMN 2.0 editor** - Busybee works with standard BPMN files
+
+Here's a minimal example you can save as `simple_process.bpmn`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  xmlns:zeebe="http://camunda.org/schema/zeebe/1.0"
+                  id="Definitions_1"
+                  targetNamespace="http://bpmn.io/schema/bpmn">
+  <bpmn:process id="hello-world" name="Hello World" isExecutable="true">
+    <bpmn:startEvent id="Start">
+      <bpmn:outgoing>Flow1</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:endEvent id="End">
+      <bpmn:incoming>Flow1</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow1" sourceRef="Start" targetRef="End"/>
+  </bpmn:process>
+</bpmn:definitions>
+```
+
+This creates a process that starts and immediately ends. Real processes would include service tasks, gateways, and other BPMN elements.
+
+For more about BPMN modeling, see the [Camunda BPMN documentation](https://docs.camunda.io/docs/components/modeler/bpmn/).
+
+## Step 5: Deploy the Process
+
+Deploy your BPMN file to Zeebe:
+
+```ruby
+# Deploy a single file
+result = client.deploy_process("simple_process.bpmn")
+# => { "hello-world" => 2251799813685249 }
+
+# The result maps process IDs to definition keys
+process_id = result.keys.first       # => "hello-world"
+definition_key = result.values.first # => 2251799813685249
+
+# Deploy multiple files at once
+result = client.deploy_process("order.bpmn", "payment.bpmn")
+# => { "order-process" => 123, "payment-process" => 456 }
+```
+
+The returned hash maps BPMN process IDs (the `id` attribute on the `<bpmn:process>` element) to process definition keys (unique identifiers assigned by Zeebe).
+
+## Step 6: Start a Process Instance
+
+Now start an instance of your deployed process:
+
+```ruby
+# Start a basic instance
+instance_key = client.start_instance("hello-world")
+# => 2251799813685300
+
+# Start with variables
+instance_key = client.start_instance("order-process",
+  vars: { order_id: "ORD-123", customer: "Alice", total: 99.99 }
+)
+
+# Start a specific version (not the latest)
+instance_key = client.start_instance("order-process",
+  vars: { order_id: "ORD-456" },
+  version: 2
+)
+```
+
+The returned `instance_key` is the unique identifier for this process instance.
+
+## Putting It All Together
+
+Here's a complete example:
+
+```ruby
+require "busybee"
+
+# Configure for local development
+client = Busybee::Client.new(insecure: true)
+
+# Deploy the process
+deployments = client.deploy_process("workflows/order-fulfillment.bpmn")
+puts "Deployed: #{deployments.keys.join(', ')}"
+
+# Start an instance
+instance_key = client.start_instance("order-fulfillment",
+  vars: {
+    order_id: "ORD-2024-001",
+    items: ["widget", "gadget"],
+    total: 149.99
+  }
+)
+puts "Started instance: #{instance_key}"
+
+# You can now monitor this instance in Operate (web UI)
+# or interact with it via messages and signals
+```
+
+## What's Next?
+
+Now that you have a running process instance, you might want to:
+
+- **Cancel an instance**: `client.cancel_instance(instance_key)`
+- **Publish a message** to trigger a message catch event: `client.publish_message("payment-received", correlation_key: "ORD-2024-001", vars: { amount: 149.99 })`
+- **Broadcast a signal** to all waiting instances: `client.broadcast_signal("system-shutdown")`
+- **Set variables** on a running instance: `client.set_variables(instance_key, vars: { status: "approved" })`
+
+See the API Reference section below for complete documentation of all available methods.
+
+# Credential Types
+
+Busybee supports four credential types for different environments:
+
+| Type | Use Case | TLS | Authentication |
+|------|----------|-----|----------------|
+| `:insecure` | Local development, Docker, CI | No | None |
+| `:tls` | Self-hosted with TLS | Yes | Server cert only |
+| `:oauth` | Self-hosted with OAuth | Yes | OAuth2 client credentials |
+| `:camunda_cloud` | Camunda Cloud SaaS | Yes | OAuth2 (auto-configured) |
+
+## Insecure Credentials
+
+For local development with no TLS or authentication:
+
+```ruby
+client = Busybee::Client.new(insecure: true)
+
+# Or with explicit address
+client = Busybee::Client.new(insecure: true, cluster_address: "zeebe:26500")
+```
+
+## TLS Credentials
+
+For self-hosted Zeebe with TLS but no client authentication:
+
+```ruby
+client = Busybee::Client.new(
+  cluster_address: "zeebe.example.com:443",
+  certificate_file: "/path/to/ca.crt"  # Optional: custom CA certificate
+)
+```
+
+## OAuth Credentials
+
+For self-hosted Zeebe with OAuth2 authentication:
+
+```ruby
+client = Busybee::Client.new(
+  cluster_address: "zeebe.example.com:443",
+  token_url: "https://auth.example.com/oauth/token",
+  client_id: "my-client-id",
+  client_secret: "my-client-secret",
+  audience: "zeebe.example.com"
+)
+```
+
+## Camunda Cloud Credentials
+
+For Camunda Cloud, the cluster address and OAuth configuration are derived automatically:
+
+```ruby
+client = Busybee::Client.new(
+  client_id: ENV["CAMUNDA_CLIENT_ID"],
+  client_secret: ENV["CAMUNDA_CLIENT_SECRET"],
+  cluster_id: ENV["CAMUNDA_CLUSTER_ID"],
+  region: ENV["CAMUNDA_CLUSTER_REGION"]  # e.g., "bru-2", "us-east-1"
+)
+```
+
+# Next Steps
+
+For complete API documentation, error handling details, and advanced usage, see the [Client documentation](../client.md).