# Sequin

A lightweight Elixir SDK for sending, receiving, and acknowledging messages in [Sequin streams](https://github.com/sequinstream/sequin).

See the [docs on hex](https://hexdocs.pm/sequin_client/Sequin.html).

## Installation

Sequin can be installed by adding `sequin` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:sequin, "~> 0.1.0"}
  ]
end
```

## Configuration

To use Sequin in your application, you'll need to configure it in your `config.exs` file. Add the following configuration:

```elixir
# config/config.exs

config :sequin,
  base_url: System.get_env("SEQUIN_URL") || "http://localhost:7673"
```

By default, the Client is initialized using Sequin's default host and port in local development: `http://localhost:7673`

## Usage

You'll predominantly use `Sequin` to send, receive, and acknowledge [messages](https://github.com/sequinstream/sequin?tab=readme-ov-file#messages) in Sequin streams:

```elixir
# Define your stream and consumer
stream = "your-stream-name"
consumer = "your-consumer-name"

# Send a message
case Sequin.send_message(stream, "test.1", "Hello, Sequin!") do
  {:ok, %{published: 1}} ->
    IO.puts("Message sent successfully")

  {:error, error} ->
    IO.puts("Error sending message: #{Exception.message(error)}")
end

# Receive a message
with {:ok, %{message: message, ack_id: ack_id}} <- Sequin.receive_message(stream, consumer),
     :ok <- YourApp.process_message(message),
     :ok <- Sequin.ack_message(stream, consumer, ack_id) do
  IO.puts("Received and acked message: #{inspect(message)}")
else
  {:ok, nil} ->
    IO.puts("No messages available")

  {:error, error} ->
    IO.puts("Error: #{Exception.message(error)}")
end
```

## Testing

To adequately test Sequin, we recommend creating temporary streams and consumers in addition to testing sending and receiving messages. Here's an example using ExUnit:

```elixir
defmodule SequinTest do
  use ExUnit.Case
  alias Sequin

  @stream_name "test-stream-#{System.system_time(:second)}"
  @consumer_name "test-consumer-#{System.system_time(:second)}"

  test "Stream and Consumer Lifecycle" do # Create a new stream
    {:ok, %Sequin.Stream{name: stream_name}} = Sequin.create_stream(@stream_name)

    # Create a consumer
    {:ok, %Sequin.Consumer{name: consumer_name}} = Sequin.create_consumer(@stream_name, @consumer_name, "test.>")

    # Send a message
    assert {:ok, %{published: 1}} = Sequin.send_message(@stream_name, "test.1", "Hello, Sequin!")

    # Receive and ack a message
    with {:ok, %Sequin.Message{} = message} <- Sequin.receive_message(@stream_name, @consumer_name),
        # do work
        :ok <- Sequin.ack_message(@stream_name, @consumer_name, message.ack_id) do
      IO.puts("Received and acked message: #{inspect(message)}")
    else
      {:error, error} ->
        IO.puts("Error: #{Exception.message(error)}")
    end

    # Delete the consumer
    {:ok, delete_consumer_res} = Sequin.delete_consumer(@stream_name, @consumer_name)

    # Delete the stream
    {:ok, delete_stream_res} = Sequin.delete_stream(@stream_name)
  end
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/sequin>.