OCaml Zulip Library with Requests#

A complete OCaml implementation of the Zulip REST API using the requests HTTP library.

Features#

• ✅ Full Zulip REST API client implementation
• ✅ Uses the modern requests library for HTTP communication
• ✅ EIO-based asynchronous operations
• ✅ Bot framework for building interactive bots
• ✅ Support for Atom/RSS feed bots

Installation#

dune build
dune install

Configuration#

Create a ~/.zuliprc file with your Zulip credentials:

[api]
email = bot@example.com
key = your-api-key-here
site = https://your-domain.zulipchat.com

Usage#

Basic Client#

open Eio_main

let () =
  run @@ fun env ->

  (* Load authentication *)
  let auth = Zulip.Auth.from_zuliprc () |> Result.get_ok in

  (* Create client *)
  Eio.Switch.run @@ fun sw ->
  let client = Zulip.Client.create ~sw env auth in

  (* Send a message *)
  let message = Zulip.Message.create
    ~type_:`Channel
    ~to_:["general"]
    ~topic:"Hello"
    ~content:"Hello from OCaml!"
    ()
  in

  match Zulip.Messages.send client message with
  | Ok response -> Printf.printf "Sent message %d\n" (Zulip.Message_response.id response)
  | Error e -> Printf.eprintf "Error: %s\n" (Zulip.Error.message e)

Atom Feed Bot#

The library includes a complete Atom/RSS feed bot that can:

• Monitor multiple feeds
• Post updates to specific Zulip channels and topics
• Track which entries have been posted
• Run as a scheduled daemon or interactive bot

Scheduled Mode#

# Run the feed bot in scheduled mode
dune exec atom_feed_bot

Interactive Mode#

# Run as an interactive bot that responds to commands
dune exec atom_feed_bot interactive

Bot commands:

• !feed add <name> <url> <topic> - Add a new feed
• !feed remove <name> - Remove a feed
• !feed list - List all feeds
• !feed fetch <name> - Manually fetch a feed
• !feed help - Show help

Architecture#

Core Library (zulip)#

• Auth: Authentication and credential management
• Client: HTTP client using the requests library
• Messages: Send, edit, and retrieve messages
• Channels: Channel/stream management
• Users: User management
• Events: Real-time event handling

Bot Framework (zulip_bot)#

• Bot_handler: Interface for bot logic
• Bot_runner: Manages bot lifecycle
• Bot_storage: State persistence
• Bot_config: Configuration management

Key Changes from Original Implementation#

1. HTTP Library: Migrated from cohttp-eio to the requests library
2. Configuration: Removed toml dependency, uses simple INI parser
3. Type Safety: Made Client.t parametric over environment types
4. Authentication: Simplified auth handling with built-in INI parser

Examples#

See the examples/ directory for:

• test_client.ml - Basic client functionality test
• atom_feed_bot.ml - Complete Atom/RSS feed bot implementation

Testing#

# Build the library
dune build

# Run the test client
dune exec test_client

# Run the atom feed bot
dune exec atom_feed_bot

Requirements#

• OCaml 4.08+
• Dune 3.0+
• eio
• requests
• jsonm
• uri
• base64