Небольшое изменение:

* изменен типа megaplan.Response для удобства работы через дженерики
* функция ParseResponse изменена, теперь она работае с новой реализацией типа megaplan.Response[T]
* версия go понижена до 1.18, где появились дженерики

Author: stvoidit

README.md

@@ -1,7 +1,8 @@
 # Пример использования
 
-Иниализация клиента + опция включения заголовка "Accept-Encoding":"gzip", ответ будет возвращаться сжатым:
+Иниализация клиента + опция включения заголовка "Accept-Encoding":"gzip", ответ будет возвращаться сжатым, реализована декомпрессия тела ответа внутри вызова.
 
+```golang
     import (
         "github.com/stvoidit/megaplan/v3"
     )
@@ -12,42 +13,44 @@
     func main() {
         client := megaplan.NewClient(domain, token, megaplan.OptionEnableAcceptEncodingGzip(true))
     }
-
+```
 ## Пример создания задачами
 https://demo.megaplan.ru/api/v3/docs#entityTask
-Для удобства составления json для тела запроса есть функция __megaplan.BuildQueryParams__. Её единственное название - собрать параметры в правильном формате.
+Для удобства составления json для тела запроса есть функция __megaplan.BuildQueryParams__. Её единственное назначение - собрать параметры в правильном формате.
 Некоторые сущности требуют специального формата (например [Дата и Время](https://demo.megaplan.ru/api/v3/docs#entityDateTime), [Интервал](https://demo.megaplan.ru/api/v3/docs#entityDateInterval), [Дата](https://demo.megaplan.ru/api/v3/docs#entityDateOnly), [~~Сдвиг дат~~](https://demo.megaplan.ru/api/v3/docs#entityShiftDate)), то функция __megaplan.BuildQueryParams__ корректно сформирует структуру этих сущностей.
 
-    func CreateTask(c *megaplan.ClientV3) {
-        const endpoint = "/api/v3/task"
-        var qp = megaplan.BuildQueryParams(
-            megaplan.SetRawField("contentType", "Task"),
-            megaplan.SetRawField("isUrgent", false),
-            megaplan.SetRawField("isTemplate", false),
-            megaplan.SetRawField("name", "library test"),
-            megaplan.SetRawField("subject", "subject library test"),
-            megaplan.SetRawField("statement", "statement library test"),
-            megaplan.SetEntityField("owner", "Employee", 1000129),
-            megaplan.SetEntityField("responsible", "Employee", 1000129),
-            megaplan.SetEntityField("deadline", "DateOnly", time.Now().Add(time.Hour*72)),
-            megaplan.SetEntityField("plannedWork", "DateInterval", time.Hour*13),
-        )
-        r, err := qp.ToReader()
-        if err != nil {
-            panic(err)
-        }
-        rc, err := c.DoRequestAPI(http.MethodPost, endpoint, nil, r)
-        if err != nil {
-            panic(err)
-        }
-        defer rc.Close()
-        os.Stdout.ReadFrom(rc)
-    }
 
+```golang
+func CreateTask(c *megaplan.ClientV3) {
+    const endpoint = "/api/v3/task"
+    var qp = megaplan.BuildQueryParams(
+        megaplan.SetRawField("contentType", "Task"),
+        megaplan.SetRawField("isUrgent", false),
+        megaplan.SetRawField("isTemplate", false),
+        megaplan.SetRawField("name", "library test"),
+        megaplan.SetRawField("subject", "subject library test"),
+        megaplan.SetRawField("statement", "statement library test"),
+        megaplan.SetEntityField("owner", "Employee", 1000129),
+        megaplan.SetEntityField("responsible", "Employee", 1000129),
+        megaplan.SetEntityField("deadline", "DateOnly", time.Now().Add(time.Hour*72)),
+        megaplan.SetEntityField("plannedWork", "DateInterval", time.Hour*13),
+    )
+    r, err := qp.ToReader()
+    if err != nil {
+        panic(err)
+    }
+    rc, err := c.DoRequestAPI(http.MethodPost, endpoint, nil, r)
+    if err != nil {
+        panic(err)
+    }
+    defer rc.Close()
+    os.Stdout.ReadFrom(rc)
+}
+```
 ## Пример запроса с параметрами URL
 Так как параметры запроса на api "Мегаплан" передаются в нетипичном формате ("*?json=?"), то необходимо их экранировать через url.QueryEscape.
 Для удобства составления этих параметров можно так же использовать тип __megaplan.QueryParams__.
-
+```golang
     func testGetWithFilters(c *megaplan.ClientV3) {
         const endpoint = "/api/v3/task"
         var requestedFiled = [...]string{
@@ -141,9 +144,78 @@ https://demo.megaplan.ru/api/v3/docs#entityTask
             os.Stdout.ReadFrom(response.Body)
         }
     }
+```
+
+## Чтение ответа
+С появлением дженериков улучшена функция для чтения ответов от api.
+Внутри функции есть проверка на Content-Type, если это не json, то в 99% это html с ошибкой. В этом случае функция вернет ошибку с текстом в виде html строки.
+
+
+```golang
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/stvoidit/megaplan/v3"
+)
+
+const (
+	DOMAIN      = `https://example.ru`
+	TOKEN       = `TOKEN`
+	ACCOUNTINFO = `/api/v3/accountInfo`
+)
+
+type AccountInfo struct {
+	ID                string         `json:"id"`
+	ContentType       string         `json:"contentType"`
+	PermanentHost     string         `json:"permanentHost"`
+	AccountName       string         `json:"accountName"`
+	BuildVersion      string         `json:"buildVersion"`
+	SystemProductName string         `json:"systemProductName"`
+	TarifId           string         `json:"tarifId"`
+	LicenceEndDate    map[string]any `json:"licenceEndDate"`
+	MobileEndDate     map[string]any `json:"mobileEndDate"`
+	PaidToDate        map[string]any `json:"paidToDate"`
+	LicenseExpired    bool           `json:"licenseExpired"`
+	MegamailDomain    string         `json:"megamailDomain"`
+	DaysRemaining     int            `json:"daysRemaining"`
+	TimeCreated       string         `json:"timeCreated"`
+}
+
+func (ai AccountInfo) String() string {
+	var sb strings.Builder
+	e := json.NewEncoder(&sb)
+	e.SetIndent("", "  ")
+	e.Encode(&ai)
+	return sb.String()
+}
+
+func main() {
+	c := megaplan.NewClient(DOMAIN, TOKEN,
+		megaplan.OptionEnableAcceptEncodingGzip(true),
+		megaplan.OptionInsecureSkipVerify(true))
+	res, err := c.DoRequestAPI(http.MethodGet, ACCOUNTINFO, nil, nil)
+	if err != nil {
+		panic(err)
+	}
+    // Вы можете указать типа как "any", если вам нужно стандартное поведение json.Decode - возврат в виде map[string]any
+	body, err := megaplan.ParseResponse[AccountInfo](res)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(body)
+}
+```
+
 
 ## __!__ Про типы и сущности "мегаплана" __!__
 
+\* _не актуально с появлением дженериков_
+
 Многие реализации библиотек для API "Мегаплана" пытаются строго типизировать и описать полностью сущности, которыми оперирует "Мегаплан".
 Однако это подход влечет за собой обязанность этих библиотек поддерживать согласованность с версиями "Мегаплана", а так же каким-то образом поддерживать кастомные варианты полей.
 Данная библиотека является просто оберткой для использования API v3 и включает минимальное кол-во вспомогательных функций для составления запросов и парсинга ответов.

apiClient.go

@@ -43,9 +43,9 @@ func NewClient(domain, token string, opts ...ClientOption) (c *ClientV3) {
 
 // ClientV3 - клиент
 type ClientV3 struct {
-	client         *http.Client
 	domain         string
 	defaultHeaders http.Header
+	client         *http.Client
 }
 
 // Do - http.Do + установка обязательных заголовков + декомпрессия ответа, если ответ сжат
@@ -54,7 +54,7 @@ func (c *ClientV3) Do(req *http.Request) (*http.Response, error) {
 	for h := range c.defaultHeaders {
 		req.Header.Set(h, c.defaultHeaders.Get(h))
 	}
-	if req.Header.Get(ct) == "" {
+	if _, ok := req.Header[ct]; !ok {
 		req.Header.Set(ct, "application/json")
 	}
 	res, err := c.client.Do(req)

apiQueryParams.go

@@ -8,9 +8,9 @@ import (
 )
 
 // QueryParams - параметры запроса
-type QueryParams map[string]interface{}
+type QueryParams map[string]any
 
-// QueryEscape - urlencode для запроса
+// QueryEscape - urlencode для запроса в строке параметрво
 func (qp QueryParams) QueryEscape() string {
 	b, _ := qp.ToJSON()
 	return url.QueryEscape(string(b))
@@ -19,7 +19,7 @@ func (qp QueryParams) QueryEscape() string {
 // ToJSON - маршализация параметров в JSON
 func (qp QueryParams) ToJSON() ([]byte, error) { return json.Marshal(&qp) }
 
-// ToReader - преобразование с JSON и io.Reader для удобства записи в http.Request
+// ToReader - получить io.Reader для добавление в body часть http.Request
 func (qp QueryParams) ToReader() (io.Reader, error) {
 	b, err := qp.ToJSON()
 	if err != nil {
@@ -31,6 +31,6 @@ func (qp QueryParams) ToReader() (io.Reader, error) {
 // PrettyPrintJSON - SetIndent для читабельного вывода
 func (qp QueryParams) PrettyPrintJSON(w io.Writer) error {
 	enc := json.NewEncoder(w)
-	enc.SetIndent("", "\t")
+	enc.SetIndent("", "  ")
 	return enc.Encode(qp)
 }

apiRequest.go

@@ -25,7 +25,7 @@ type QueryBuildingFunc func(QueryParams)
 
 // CreateEnity - создать базовую сущность в формате "Мегаплана"
 // ! могут быть не описаны крайние или редкоиспользуемые типы
-func CreateEnity(contentType string, value interface{}) (qp QueryParams) {
+func CreateEnity(contentType string, value any) (qp QueryParams) {
 	qp = make(QueryParams, 2)
 	qp["contentType"] = contentType
 
@@ -62,7 +62,7 @@ func CreateEnity(contentType string, value interface{}) (qp QueryParams) {
 }
 
 // SetEntityField - добавить поле с сущностью
-func SetEntityField(fieldName string, contentType string, value interface{}) (qbf QueryBuildingFunc) {
+func SetEntityField(fieldName string, contentType string, value any) (qbf QueryBuildingFunc) {
 	return func(qp QueryParams) { qp[fieldName] = CreateEnity(contentType, value) }
 }
 
@@ -72,7 +72,7 @@ func SetEntityArray(field string, ents ...QueryBuildingFunc) QueryBuildingFunc {
 		if len(ents) == 0 {
 			return
 		}
-		var arr = make([]interface{}, len(ents))
+		var arr = make([]any, len(ents))
 		var tmpParams = make(QueryParams)
 		for i, ent := range ents {
 			ent(tmpParams)
@@ -83,19 +83,19 @@ func SetEntityArray(field string, ents ...QueryBuildingFunc) QueryBuildingFunc {
 }
 
 // SetRawField - добавить поле с простым типом значения (string, int, etc.)
-func SetRawField(field string, value interface{}) QueryBuildingFunc {
+func SetRawField(field string, value any) QueryBuildingFunc {
 	return func(qp QueryParams) { qp[field] = value }
 }
 
 // UploadFile - загрузка файла, возвращает обычный http.Response, в ответе стандартная структура ответа + данные для базовой сущности
-func (c *ClientV3) UploadFile(filename string, fileRader io.Reader) (*http.Response, error) {
+func (c *ClientV3) UploadFile(filename string, fileReader io.Reader) (*http.Response, error) {
 	var buf bytes.Buffer // default 1024 bytes buffer
 	var mw = multipart.NewWriter(&buf)
 	fw, err := mw.CreateFormFile("files[]", filename)
 	if err != nil {
 		return nil, err
 	}
-	if _, err := io.Copy(fw, fileRader); err != nil {
+	if _, err := io.Copy(fw, fileReader); err != nil {
 		return nil, err
 	}
 	if err := mw.Close(); err != nil {

apiResponse.go

@@ -6,25 +6,26 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net/http"
 	"strings"
 )
 
 // Response - ответ API
-type Response struct {
-	Meta Meta        `json:"meta"` // metainfo ответа
-	Data interface{} `json:"data"` // поле для декодирования присвоенной структуры
+type Response[T any] struct {
+	Meta Meta `json:"meta"` // metainfo ответа
+	Data T    `json:"data"` // поле для декодирования присвоенной структуры
 }
 
 // Next - есть ли следующая страница
-func (res Response) Next() bool { return res.Meta.Pagination.HasMoreNext }
+func (res Response[T]) Next() bool { return res.Meta.Pagination.HasMoreNext }
 
 // Prev - есть ли предыдущая страница
-func (res Response) Prev() bool { return res.Meta.Pagination.HasMorePrev }
+func (res Response[T]) Prev() bool { return res.Meta.Pagination.HasMorePrev }
 
 // Decode - парсинг ответа API
-func (res *Response) Decode(r io.Reader, i interface{}) (err error) {
-	res.Data = i
-	if err := json.NewDecoder(r).Decode(res); err != nil {
+func (res *Response[T]) Decode(r *http.Response) (err error) {
+	defer r.Body.Close()
+	if err := json.NewDecoder(r.Body).Decode(res); err != nil {
 		return err
 	}
 	return res.Meta.Error()
@@ -85,10 +86,10 @@ func (p Pagination) MarshalJSON() ([]byte, error) { return nil, nil }
 // Meta - metainfo
 type Meta struct {
 	Errors []struct {
-		Fields  interface{} `json:"field"`
-		Message interface{} `json:"message"`
+		Fields  any `json:"field"`
+		Message any `json:"message"`
 	} `json:"errors"`
-	Status     int64      `json:"status"`
+	Status     int        `json:"status"`
 	Pagination Pagination `json:"pagination"`
 }
 
@@ -104,12 +105,18 @@ func (m Meta) Error() (err error) {
 	return
 }
 
-// ParseResponse - обертка над методов Response.Decode + данные о пагинации
-// utility-функция для упрощения чтения ответа API
-func ParseResponse(r io.Reader, i interface{}) (next bool, prev bool, err error) {
-	var res Response
-	if err := res.Decode(r, i); err != nil {
-		return res.Next(), res.Prev(), err
+// ParseResponse - utility-функция для упрощения чтения ответа API
+func ParseResponse[T any](r *http.Response) (res Response[T], err error) {
+	defer r.Body.Close()
+	if !strings.Contains(r.Header.Get("Content-Type"), "application/json") {
+		b, err := io.ReadAll(r.Body)
+		if err != nil {
+			return res, err
+		}
+		return res, errors.New(string(b))
 	}
-	return res.Next(), res.Prev(), nil
+	e := json.NewDecoder(r.Body)
+	e.UseNumber()
+	err = e.Decode(&res)
+	return
 }

go.mod

@@ -1,3 +1,3 @@
 module github.com/stvoidit/megaplan/v3
 
-go 1.19
+go 1.18