From d862788b8ddeb87f69b7e497892862f84048ffc2 Mon Sep 17 00:00:00 2001
From: Henrik Hautakoski <henrik.hautakoski@gmail.com>
Date: Wed, 7 Feb 2024 17:56:19 +0100
Subject: [PATCH] Add api/README.md

---
 api/README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 api/README.md

diff --git a/api/README.md b/api/README.md
new file mode 100644
index 0000000..b39cea6
--- /dev/null
+++ b/api/README.md
@@ -0,0 +1,104 @@
+# Thalos Golang API
+
+## Usage
+
+The api is designed with callback functions that are called when messages arrive
+
+## Example
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+
+	"github.com/eosswedenorg/thalos/api"
+	"github.com/eosswedenorg/thalos/api/message"
+	_ "github.com/eosswedenorg/thalos/api/message/json"
+	api_redis "github.com/eosswedenorg/thalos/api/redis"
+	"github.com/redis/go-redis/v9"
+)
+
+func main() {
+	// Create redis client
+	rdb := redis.NewClient(&redis.Options{})
+
+	sub := api_redis.NewSubscriber(context.Background(), rdb, api_redis.Namespace{
+		Prefix:  "ship",
+		ChainID: "1064487b3cd1a897ce03ae5b6a865651747e2e152090f99c1d19d44e01aea5a4", // Wax mainnet.
+	})
+
+    // Create client
+	codec, err := message.GetCodec("json")
+	if err != nil {
+		fmt.Println("Failed to get json codec")
+		return
+	}
+
+	client := api.NewClient(sub, codec.Decoder)
+
+    // Subscribe to some channels.
+	err = client.Subscribe(
+		api.TransactionChannel,
+		api.ActionChannel{Contract: "eosio"}.Channel(),
+		api.ActionChannel{Name: "mine"}.Channel(),
+		api.HeartbeatChannel,
+		api.TableDeltaChannel{}.Channel(),
+	)
+
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+
+    // Wait for interrupt in a go routine and close the client.
+	go func() {
+		sig := make(chan os.Signal)
+		signal.Notify(sig, os.Interrupt)
+
+		<-sig
+		fmt.Println("Got interrupt")
+
+		client.Close()
+	}()
+
+    // Read messages
+	for t := range client.Channel() {
+		switch msg := t.(type) {
+		case error:
+			fmt.Println("Error:", msg)
+		case message.TransactionTrace:
+			fmt.Println("Transaction", msg.BlockNum, msg.ID)
+			fmt.Println(msg)
+			fmt.Println("---")
+		case message.HeartBeat :
+			fmt.Println("Heartbeat")
+			fmt.Println(msg)
+			fmt.Println("---")
+		}
+	}
+}
+
+
+
+```
+
+## Message channels and types
+
+There are several types of channels to subscribe to aswell with their respectivly
+message types.
+
+NOTE: this is not the same as an go channel. all messages will be posted to the same go channel that can
+be accessed by `client.Channel()`
+
+| Channel type         | Message type       | Description                                                                                                          |
+| -------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| -                    | `error`            | Posted if an error occured on the client. There is no channel to subscribe to. error messages will always be posted. |
+| `HeartbeatChannel`   | `HeartBeat`        | Heartbeat message. Used to know if thalos is there or not if messages are not posted frequently on real channels.    |
+| `RollbackChannel`    | `RollbackMessage`  | This message is posted if the chain has experienced a microfork.                                                     |
+| `TransactionChannel` | `TransactionTrace` | Information about an transaction                                                                                     |
+| `ActionChannel`      | `ActionTrace`      | Information about an action                                                                                          |
+| `TableDeltaChannel`  | `TableDelta`       | Information about an table change                                                                                    |