feat: enhance readme with useage examples

src/odpf/proton/raccoon/readme.md

@@ -1,6 +1,58 @@
-This folder contains the schema of request and response used in [Raccoon](https://github.com/odpf/raccoon). Raccoon's client uses `EventRequest` to push `Event`s to Raccoon. Raccoon supports arbitrary event schema by accepting it in byte form. The response can be handled by parsing the byte returned with `EventResponse`.
+This folder contains the contract between [Raccoon](https://github.com/odpf/raccoon) and the client. The client sends the request in form of bytes serialized `EventRequest` proto. `EventRequest` contains repeated `Event` field. `Event` is where you put your bytes serialized event. Because the event is serialized as bytes, you can put any kind of event structured in any kind of schema as per your requirement. This makes Raccoon event-agnostic. You can send any form of events. After the request is sent, Raccoon will process it and give back the response in form of `EventResponse`. The client can handle the response such as retry the request in case of failure. See the illustration below for more clarity.
 
+<p align="center"><img src="./../../../../docs/assets/raccoon-reqres.svg"/></p>
+
+For details of each field in each proto, you can open the proto files and read the comment.
 ### How to use
-First, you need to [compile](https://developers.google.com/protocol-buffers/docs/reference/overview) the protos. Serialize events you want to send as bytes. After that, you can use the compiled proto to build the `EventRequest` and send it via Raccoon's supported protocol. For details of the schema, you can open each protos and read the field description.
+Since proton only provides the proto files. You need to [compile](https://developers.google.com/protocol-buffers/docs/reference/overview) the proto files yourself according to your language of choice. Then, use the generated code to build the request or parse the response.
+#### Javascript Example
+There are [2 packaging options](https://developers.google.com/protocol-buffers/docs/reference/javascript-generated#invocation) provided by the [default protoc](https://github.com/protocolbuffers/protobuf) to compile the proto to javascript code. For this example we are using [commonjs](https://developers.google.com/protocol-buffers/docs/reference/javascript-generated#commonjs-imports).
+To compile the proto files you can go to `proton` root directory and enter:
+```
+protoc --proto_path=src --js_out=import_style=commonjs,binary:. odpf/proton/raccoon/Event.proto odpf/proton/raccoon/EventRequest.proto odpf/proton/raccoon/EventResponse.proto
+```
+The command will generate the javascript package under `odpf/proton/raccoon`. You'll see 3 files with `_pb.js` suffix. You can move those generated codes to your project and import them.
+
+Javascript generated code requires `google-protobuf` as dependency. Make sure to include it in your `package.json`.
+
+Now, you got Javascript generated code in your project. You only need to import it and build the request or parse the response. See example below:
+```
+const { Timestamp } = require('google-protobuf/google/protobuf/timestamp_pb.js');
+const { EventRequest } = require('./EventRequest_pb');
+const { Event } = require('./Event_pb');
+
+const userClickEvent = {
+  user_id: 'user-12783',
+  event: 'order_clicked',
+  timestamp: 1617092381,
+};
+
+const event = new Event();
+event.setEventbytes(Buffer.from(JSON.stringify(userClickEvent)));
+event.setType('click_event');
+
+const sentTime = new Timestamp();
+sentTime.fromDate(new Date());
+
+const request = new EventRequest();
+request.setReqGuid('123123');
+request.setSentTime(sentTime);
+request.setEventsList([event]);
+
+sendRequestToRaccoon(request.serializeBinary());
+```
+
+You can use the same generated package to deserialize the response from Raccoon.
+```
+const { EventResponse } = require('./EventResponse_pb');
+
+const binaryResponse = getResonseFromRaccoon();
+const response = new EventResponse();
+response.deserializeBinary(binaryResponse);
+```
+#### Raccoon Example
 
-For example of how to build the protos, you can see Raccoon's `Makefile`.
+We also compile the proto in GO for Raccoon. You can check how the code is generated by looking at the Makefile. In general, it does the following:
+1. Pull the proto from `proton`
+2. Generate the GO code and place it internal package
+3. Packages that require the proto can import it from the internal package