ExPlain

An Elixir client for the Plain GraphQL API.

Installation

Add ex_plain to your dependencies in mix.exs:

def deps do
  [
    {:ex_plain, "~> 0.2.0"}
  ]
end

Quick start

client = ExPlain.new(api_key: System.fetch_env!("PLAIN_API_KEY"))

# Look up a customer
{:ok, customer} = ExPlain.Customers.get_by_email(client, "alice@example.com")

# Create a thread
{:ok, thread} = ExPlain.Threads.create(client, %{
  customer_identifier: %{customer_id: customer.id},
  title: "Cannot log in"
})

Domains covered

Module	Operations
`ExPlain.Customers`	upsert, get, list, delete, manage groups
`ExPlain.Threads`	create, assign, label, reply, change status
`ExPlain.Companies`	upsert, get, list
`ExPlain.Tenants`	upsert, get, list, manage customers
`ExPlain.Tiers`	upsert, get, list
`ExPlain.Labels`	list label types, add/remove labels on threads
`ExPlain.Events`	create customer and thread timeline events
`ExPlain.Users`	list users, get current user
`ExPlain.Webhooks`	list, create, update, delete webhook targets

Pagination

List operations follow the Relay cursor pagination convention. Pass first: and after: (or last: and before:) keyword options; the response is a map with :nodes and :page_info.

{:ok, page} = ExPlain.Customers.list(client, first: 50)
next_cursor = page.page_info.end_cursor
{:ok, page2} = ExPlain.Customers.list(client, first: 50, after: next_cursor)

Error handling

All functions return {:ok, result} or {:error, %ExPlain.Error{}}. Mutation errors from Plain (validation failures, permission errors) come back as {:error, %ExPlain.Error{type: :mutation_error}} with field-level detail when available.

case ExPlain.Customers.upsert(client, input) do
  {:ok, %{result: :created, customer: customer}} -> customer
  {:error, %ExPlain.Error{type: :mutation_error, message: msg}} -> {:error, msg}
  {:error, %ExPlain.Error{type: :forbidden}} -> {:error, :unauthorized}
end

Testing

Pass a plug: option to use Req.Test for HTTP stubbing without real network calls:

client = ExPlain.new(api_key: "test_key", plug: {Req.Test, __MODULE__})

Req.Test.stub(__MODULE__, fn conn ->
  Req.Test.json(conn, %{"data" => %{"customer" => %{"id" => "c_01", ...}}})
end)

Documentation

Full API documentation is available on HexDocs.