github.com/sharovik/devbot@v1.0.1-0.20240308094637-4a0387c40516/documentation/available-features.md (about)

     1  # Available internal features
     2  Here you can see the list potential useful features of the project, which can be useful during your custom events build.
     3  
     4  ## Table of contents
     5  - [BitBucket API client](#bitbucket-api-client)
     6  - [Slack API client](#slack-api-client)
     7  - [Http client](#http-client)
     8  - [Migrations service](migrations.md)
     9  - [Available helper functions](#available-helper-functions)
    10  - [Logger](#logger)
    11  - [Scenarios](scenarios.md)
    12  - [Database query builder](query-builder.md)
    13  
    14  ## BitBucket API client
    15  The client, which can be used for custom requests to the BitBucket API. The good examples of usage of that client are [bb release](https://github.com/sharovik/bitbucket-release-event) and [start pipeline](https://github.com/sharovik/bitbucket-run-pipeline) events. Feel free to check the source of these events.
    16  
    17  ### Source
    18  You can find the source here: `internal/client/bitbucket.go`
    19  
    20  ### Basic example
    21  Imagine you have your own custom event. This bitbucket API client is injected by default into container. To use the features of the BitBucket client you can do the next steps:
    22  1. select the method from available public methods
    23  2. use selected method in your custom event
    24  ```
    25  //... some code of your event here
    26  accessToken, err := container.C.BibBucketClient.GetAuthToken()
    27  if err != nil {
    28  	return
    29  }
    30  //... now you have access to the access token of bitbucket API
    31  ```
    32  
    33  ## Slack API client
    34  With this client you can send the messages to a specific channel/user, attache files to a specific channel or do a custom requests to the slack events API
    35  
    36  ### Source
    37  You can find the source here: `internal/client/slack.go`
    38  
    39  ### Basic example
    40  Let's imagine you have your own custom event, where you need to send the message to a specific user. 
    41  ``` 
    42  //... some code of your event here
    43  response, statusCode, err := container.C.MessageClient.SendMessage(dto.SlackRequestChatPostMessage{
    44      Channel:           "SLACK_UID",
    45      Text:              "This is the test message",
    46      AsUser:            true,
    47      Ts:                time.Time{},
    48      DictionaryMessage: dto.DictionaryMessage{},
    49      OriginalMessage:   dto.SlackResponseEventMessage{},
    50  })
    51  if err != nil {
    52      log.Logger().AddError(err).
    53          Interface("response", response).
    54          Interface("status", statusCode).
    55          Msg("Failed to sent answer message")
    56  }
    57  //If there was no error, that means the message was sent to the "SLACK_UID"
    58  ```
    59  
    60  ## Http Client
    61  This is a simple http client, which can be used for requests to your custom API gateways.
    62  
    63  ### Source
    64  You can find the source here: `internal/client/http.go`
    65  
    66  ### Basic example
    67  With the Http client you can trigger your custom API endpoints. The client supports next type of the requests: `GET`, `POST`, `PUT` and of course there is always possibility to use your custom request type via `Request` method.
    68  
    69  Request via available `GET`, `POST`, `PUT` methods.
    70  ```
    71  //... some custom code of your event
    72  container.C.HTTPClient.SetBaseURL({YOUR_BASE_URL})
    73  
    74  //We define the form which we need to sent to the API endpoint
    75  form := url.Values{}
    76  form.Add("some_key", "this is some key value")
    77  form.Add("some_other_key", "this is some other key value")
    78  
    79  //Actual API POST request using form request
    80  response, statusCode, err := container.C.HTTPClient.Post({YOUR_ENDPOINT_HERE}, form, map[string]string{})
    81  if err != nil {
    82      log.Logger().AddError(err).
    83          Str("endpoint", {YOUR_ENDPOINT_HERE}).
    84          Int("status_code", statusCode).
    85          RawJSON("response", response).
    86          Msg("Error received during API request")
    87  }
    88  ```
    89  
    90  Or if your API supports the json requests
    91  ```
    92  //... some custom code of your event
    93  type Request struct {
    94  	Name   string                `json:"name"`
    95  }
    96  
    97  var request := Request{
    98      Name: "test",
    99  }
   100  
   101  byteRequest, err := json.Marshal(request)
   102  if err != nil {
   103      log.Logger().AddError(err).
   104          Interface("request", request).
   105          Msg("Error during marshal of the request")
   106  }
   107  
   108  container.C.HTTPClient.SetBaseURL({YOUR_BASE_URL})
   109  response, statusCode, err := b.client.Post({YOUR_ENDPOINT_HERE}, byteRequest, map[string]string{})
   110  if err != nil {
   111      log.Logger().AddError(err).
   112          Int("status_code", statusCode).
   113          RawJSON("response", response).
   114          Msg("The request failed")
   115  }
   116  ```
   117  
   118  Now let's try to make DELETE request via `Request` method
   119  ``` 
   120  //... some custom code of your event
   121  
   122  //In that case you don't need to define the base url 
   123  //container.C.HTTPClient.SetBaseURL({YOUR_BASE_URL})
   124  //so you can write the full endpoint url including the base url
   125  response, statusCode, err := client.Request(http.MethodDelete, {YOUR_FULL_API_ENDPOINT_URL}, interface{}, map[string]string{})
   126  if err != nil {
   127      log.Logger().AddError(err).
   128          Int("status_code", statusCode).
   129          RawJSON("response", response).
   130          Msg("The request failed")
   131  }
   132  ```
   133  
   134  The `Request` method currently supports next types of `body` parameter:
   135  1. `string` - when we need to send a simple string to selected endpoint
   136  2. `url.Values` - when we need to send the form-data
   137  3. `[]byte` - when we need to send the json requests
   138  
   139  ## Available helper functions
   140  These functions can be used in different cases and can help you. All these functions are public and available in `github.com/sharovik/devbot/internal/helper` package
   141  
   142  ### Source
   143  You can find the source here: `internal/helper/helper.go`
   144  
   145  ### Basic example
   146  ``` 
   147  import "github.com/sharovik/devbot/internal/helper"
   148  
   149  //... some custom code of your event
   150  matches := helper.FindMatches(`(?i)(help)`, "Can you find the help word in this string?")
   151  if len(matches) != 0 {
   152      fmt.Println("Yes I can.")
   153  }
   154  ```
   155  
   156  ## Logger
   157  The logger is based on the zerolog library, which you can find [here](https://github.com/rs/zerolog).
   158  
   159  There is a several method which can be using for the logging actions in your custom event.
   160  ### Source
   161  You can find the source here: `internal/log/logger.go`
   162  
   163  ### Basic example
   164  This is the simple usage of the logger
   165  ``` 
   166  //... some code of your event
   167  log.Logger().Info().Str("some_field", "The value").Msg("This is the test log")
   168  ```
   169  But once you need to have a global context in your project, you can use `AppendGlobalContext` method to append the values to a global context. After this log trigger, these values will be available in `context` attribute of all logs.
   170  ``` 
   171  //... some code of your event
   172  numberOfRetries := 1
   173  log.Logger().AppendGlobalContext(map[string]interface{}{
   174      "number_retries": numberOfRetries,
   175  })
   176  ```