chore: minor fixes, doc updates and hello 2024

README.md

@@ -81,8 +81,7 @@ Feishu/Lark API offers more features, please refers to [Usage](#usage) for furth
   because Feishu and Lark basically shares the same API specification.
   We do not guarantee all of the APIs work well with Lark, until we have tested it on Lark.
 - go-lark only supports Custom App. Marketplace App is not supported yet.
-- go-lark implements bot and messaging API, other APIs such as Lark Doc, Calendar and so on are not supported.
-- go-lark implements API in v3/v4 version\* (official documents may also mention im/v1 version) and event with Schema 1.0 and 2.0 (partially).
+- go-lark implements messaging, group chat, and bot API, other APIs such as Lark Doc, Calendar and so on are not supported.
 
 ### Switch to Lark Endpoints
 
@@ -218,7 +217,7 @@ We have already implemented HTTP middlewares to support event handling:
 - [Gin Middleware](https://github.com/go-lark/lark-gin)
 - [Hertz Middleware](https://github.com/go-lark/lark-hertz)
 
-Example: [examples/gin-middleware](https://github.com/go-lark/examples/tree/main/gin-middleware)
+Example: [examples/gin-middleware](https://github.com/go-lark/examples/tree/main/gin-middleware) [examples/hertz-middleware](https://github.com/go-lark/examples/tree/main/hertz-middleware)
 
 #### URL Challenge
 
@@ -253,7 +252,20 @@ r.POST("/", func(c *gin.Context) {
 })
 ```
 
-#### Receiving Message
+#### Card Callback
+
+We may also setup callback for card actions (e.g. button). The URL challenge part is the same.
+
+We may use `LarkCardHandler` to handle the actions:
+```go
+r.Use(middleware.LarkCardHandler())
+r.POST("/callback", func(c *gin.Context) {
+    if card, ok := middleware.GetCardCallback(c); ok {
+    }
+})
+```
+
+#### Receiving Message (Event V1)
 
 For older bots, please use v1:
 
@@ -286,12 +298,10 @@ middleware.WithEncryption("<encryption-key>")
 ### Debugging
 
 Lark does not provide messaging API debugger officially. Thus, we have to debug with real Lark conversation.
-We add `PostEvent` to simulate message sending to make it easier.
-`PostEvent` can also be used to redirect message, which acts like a reverse proxy.
-
-Example: [examples/event-forward](https://github.com/go-lark/examples/tree/main/event-forward)
+We recommend [ngrok](https://ngrok.com/) to debug events.
 
-> Notice: `PostEvent` does not support AES encryption at the moment.
+And we add `PostEvent` to simulate message sending to make it even easier.
+`PostEvent` can also be used to redirect events, which acts like a reverse proxy.
 
 ## Development
 
@@ -309,7 +319,8 @@ Example: [examples/event-forward](https://github.com/go-lark/examples/tree/main/
    LARK_UNION_ID
    LARK_OPEN_ID
    LARK_CHAT_ID
-   LARK_MESSAGE_ID
+   LARK_WEBHOOK_V2
+   LARK_WEBHOOK_V2_SIGNED
    ```
 
    `LARK_APP_ID` and `LARK_APP_SECRET` are mandatory. Others are required only by specific API tests.
@@ -379,7 +390,7 @@ func CopyFile(bot *lark.Bot, fileToken, dstFolderToken, dstName string) (*CopyFi
   2. not invite to the group.
   3. API permission not applied.
 - Does go-lark support interactive message card?
-  - Yes, use card builder.
+  - Yes, use a CardBuilder.
 
 ## Contributing
 
@@ -388,4 +399,4 @@ func CopyFile(bot *lark.Bot, fileToken, dstFolderToken, dstName string) (*CopyFi
 
 ## License
 
-Copyright (c) David Zhang, 2018-2023. Licensed under MIT License.
+Copyright (c) David Zhang, 2018-2024. Licensed under MIT License.

README_zhCN.md

@@ -76,8 +76,7 @@ func main() {
 
 - go-lark 基于飞书域名进行测试，理论上可以完全兼容 Lark 平台（API 定义一致）。但我们不保证在 Lark 下完全可用，因为账户限于，没有专门测试过。
 - go-lark 仅支持企业自建应用，不支持应用商店应用（ISV）。
-- go-lark 仅实现了机器人和消息 API，对于飞书文档、日历等功能，并不支持。
-- go-lark 目前实现的是 API v3/v4 版本\*（官方文档通常还会出现 im/v1 版本）以及事件 Schema 1.0 版本。
+- go-lark 仅实现了消息、群组和机器人 API，对于飞书文档、日历等功能，并不支持。
 
 ### 切换到 Lark 域名
 
@@ -209,7 +208,7 @@ Bind 函数：
 - [Gin Middleware](https://github.com/go-lark/lark-gin)
 - [Hertz Middleware](https://github.com/go-lark/lark-hertz)
 
-实例：[examples/gin-middleware](https://github.com/go-lark/examples/tree/main/gin-middleware)
+实例：[examples/gin-middleware](https://github.com/go-lark/examples/tree/main/gin-middleware) [examples/hertz-middleware](https://github.com/go-lark/examples/tree/main/hertz-middleware)
 
 #### URL 挑战
 
@@ -223,13 +222,15 @@ r.Use(middleware.LarkChallengeHandler())
 #### 事件 2.0
 
 飞书开放平台默认事件类似目前 v2，会自动在新创建的机器人中启用。
+
 ```go
 r := gin.Default()
 middleware := larkgin.NewLarkMiddleware()
 r.Use(middleware.LarkEventHandler())
 ```
 
 获取事件详情：
+
 ```go
 r.POST("/", func(c *gin.Context) {
     if evt, ok := middleware.GetEvent(c); ok { // => GetEvent instead of GetMessage
@@ -243,9 +244,24 @@ r.POST("/", func(c *gin.Context) {
 })
 ```
 
-#### 接收消息 1.0
+#### 卡片回调
+
+我们可以使用卡片回调接受卡片的用户操作（如：按钮点击），URL 挑战部分同步上。
+
+我们可以使用 `LarkCardHandler` 来接受操作事件：
+
+```go
+r.Use(middleware.LarkCardHandler())
+r.POST("/callback", func(c *gin.Context) {
+    if card, ok := middleware.GetCardCallback(c); ok {
+    }
+})
+```
+
+#### 接收消息（事件 1.0）
 
 对于较早常见的机器人，我们需要使用 v1 版本：
+
 ```go
 r := gin.Default()
 middleware := larkgin.NewLarkMiddleware()
@@ -275,13 +291,9 @@ middleware.WithEncryption("<encryption-key>")
 ### 调试
 
 飞书官方没有提供发消息工具，如果测试消息交互的话不得不在飞书上发消息，直接在“线上” URL 调试，很不方便。
+推荐使用 [ngrok](https://ngrok.com/) 进行代理调试。
 
-我们加入了线下模拟消息事件的 `PostEvent`，通过它可以在任何地方进行调试。当然，模拟消息的包体需要自己构造。同时，我们也可以使用 `PostEvent` 对原消息进行转发，对消息进行反向代理。
-
-参考实例：[examples/event-forward](https://github.com/go-lark/examples/tree/main/event-forward)
-
-> `PostEvent`目前不支持 AES 加密。
-
+同时，我们还加入了线下模拟消息事件的 `PostEvent`，通过它可以在任何地方进行调试。当然，模拟消息的包体需要自己构造。`PostEvent` 也可以用于事件转发，对事件进行反向代理。
 
 ## 开发
 
@@ -299,7 +311,8 @@ middleware.WithEncryption("<encryption-key>")
    LARK_UNION_ID
    LARK_OPEN_ID
    LARK_CHAT_ID
-   LARK_MESSAGE_ID
+   LARK_WEBHOOK_V2
+   LARK_WEBHOOK_V2_SIGNED
    ```
 
    其中，`LARK_APP_ID` 和 `LARK_APP_SECRET` 必须配置，其它字段根据不同的测试可选择配置。
@@ -375,4 +388,4 @@ func CopyFile(bot *lark.Bot, fileToken, dstFolderToken, dstName string) (*CopyFi
 
 ## 协议
 
-Copyright (c) David Zhang, 2018-2023. Licensed under MIT License.
+Copyright (c) David Zhang, 2018-2024. Licensed under MIT License.

event_v1_test.go

@@ -0,0 +1,53 @@
+package lark
+
+import (
+	"encoding/json"
+	"io/ioutil"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPostEventMessage(t *testing.T) {
+	message := EventMessage{
+		Timestamp: "",
+		Token:     "",
+		EventType: "event_callback",
+		Event: EventBody{
+			Type:          "message",
+			ChatType:      "private",
+			MsgType:       "text",
+			OpenID:        testUserOpenID,
+			Text:          "private event",
+			Title:         "",
+			OpenMessageID: "",
+			ImageKey:      "",
+			ImageURL:      "",
+		},
+	}
+	w := performRequest(func(w http.ResponseWriter, r *http.Request) {
+		var m EventMessage
+		json.NewDecoder(r.Body).Decode(&m)
+		w.Write([]byte(m.Event.Text))
+	}, "POST", "/", message)
+	assert.Equal(t, "private event", string(w.Body.Bytes()))
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		m, _ := json.Marshal(message)
+		w.Write([]byte(m))
+	}))
+	defer ts.Close()
+	resp, err := PostEvent(http.DefaultClient, ts.URL, message)
+	if assert.NoError(t, err) {
+		var event EventMessage
+		body, err := ioutil.ReadAll(resp.Body)
+		if assert.NoError(t, err) {
+			defer resp.Body.Close()
+			_ = json.Unmarshal(body, &event)
+			assert.Equal(t, "event_callback", event.EventType)
+			assert.Equal(t, "message", event.Event.Type)
+		}
+	}
+}

event_v2.go

@@ -52,9 +52,9 @@ type EventV2UserID struct {
 
 // PostEvent with event v2 format
 // and it's part of EventV2 instead of package method
-func (e EventV2) PostEvent(client *http.Client, hookURL string, event EventV2) (*http.Response, error) {
+func (e EventV2) PostEvent(client *http.Client, hookURL string) (*http.Response, error) {
 	buf := new(bytes.Buffer)
-	err := json.NewEncoder(buf).Encode(event)
+	err := json.NewEncoder(buf).Encode(e)
 	if err != nil {
 		log.Printf("Encode json failed: %+v\n", err)
 		return nil, err

event_v2_test.go

@@ -2,18 +2,14 @@ package lark
 
 import (
 	"encoding/json"
+	"io/ioutil"
 	"net/http"
+	"net/http/httptest"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 )
 
-func httpHandlerV2(w http.ResponseWriter, r *http.Request) {
-	var m EventV2
-	json.NewDecoder(r.Body).Decode(&m)
-	w.Write([]byte(m.Schema))
-}
-
 func TestPostEventV2(t *testing.T) {
 	message := EventV2{
 		Schema: "2.0",
@@ -32,8 +28,29 @@ func TestPostEventV2(t *testing.T) {
 			ImageURL:      "",
 		},
 	}
-	w := performRequest(httpHandlerV2, "POST", "/", message)
+	w := performRequest(func(w http.ResponseWriter, r *http.Request) {
+		var m EventV2
+		json.NewDecoder(r.Body).Decode(&m)
+		w.Write([]byte(m.Schema))
+	}, "POST", "/", message)
 	assert.Equal(t, "2.0", string(w.Body.Bytes()))
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		m, _ := json.Marshal(message)
+		w.Write([]byte(m))
+	}))
+	defer ts.Close()
+	resp, err := message.PostEvent(http.DefaultClient, ts.URL)
+	if assert.NoError(t, err) {
+		var event EventV2
+		body, err := ioutil.ReadAll(resp.Body)
+		if assert.NoError(t, err) {
+			defer resp.Body.Close()
+			_ = json.Unmarshal(body, &event)
+			assert.Equal(t, "2.0", event.Schema)
+			assert.Equal(t, "666", event.Header.AppID)
+		}
+	}
 }
 
 func TestEventTypes(t *testing.T) {

logger.go

@@ -1,7 +1,6 @@
 package lark
 
 import (
-	"bytes"
 	"context"
 	"io"
 	"log"
@@ -78,11 +77,3 @@ func (bot *Bot) WithContext(ctx context.Context) *Bot {
 	bot.ctx = ctx
 	return bot
 }
-
-func (bot Bot) captureOutput(f func()) string {
-	var buf bytes.Buffer
-	bot.logger.SetOutput(&buf)
-	f()
-	bot.logger.SetOutput(os.Stderr)
-	return buf.String()
-}