feat: 添加文档介绍如何发布 npm

Signed-off-by: Ke Jie <[email protected]>

docs/contrib/ci/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "持续集成",
+  "position": 999,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/contrib/ci/intro.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+为了加速迭代，钉钉各个 SDK 陆续支持了基于 GitHub Actions 的持续集成。在代码变更之后，可以通过触发自动化构建来实现版本发布。例如 Node.js 的 SDK 代码更新后，可以通过发布 Release 触发自动构建，并推送至 npmjs.com 中。
+
+## 发布要求
+
+* 版本号遵循 https://semver.org/
+  * 主版本号：当你做了不兼容的 API 修改时候更新。原则上不升级，需要组织专项评审会议，通过评审后才允许升级主版本号；
+  * 次版本号：当你做了向下兼容的功能性新增时候更新；
+  * 修订号：当你做了向下兼容的问题修正时候更新；
+  * 特殊版本：v1.0.0 之前的版本，也即 v0.y.z 版本表示测试版本，会出现不兼容的变更。推荐采用等号（==）依赖指定的测试版本，避免使用大于等于（>=）。
+* 每次 SDK 版本发布务必有对应的 GitHub Release，以及 Release Note

docs/contrib/ci/nodejs.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 1
+---
+
+# Node.js SDK 发布
+
+本文介绍如何通过 GitHub Action 自动化发布 dingtalk-stream-sdk-nodejs 这个 SDK。
+
+核心思想是通过 GitHub Release 触发 GitHub Action 执行，在 GitHub Action 中实现了自动化构建与发布。
+
+## 步骤说明
+
+1. **更新版本号**：按照[规范](intro)，确定准备发布的版本号，例如 x.y.z。并将该版本号更新到 `package.json` 中 `version` 字段。
+   1. 建议：提交 Pull request 时候，把 package.json 中的版本变更一同提交
+2. **创建 Release**：在[项目首页](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs)，点击右侧 [Releases](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs/releases) 后，点击`Draft a new release`，填写表单完成发布
+   1. 要求：对于常规发布，Release title 中只写版本号，格式为 `vX.Y.Z`
+   2. 要求：如果是 Breaking change，需要 title 中备注，格式为 `vX.Y.Z Breaking change`
+3. **检查 CI 结果**：完成步骤 2 的 Release 之后，GitHub action 就会自动执行，可以进入 [Actions](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs/actions) 中检查构建状态及结果。
+
+## 深入理解原理
+
+该项目使用了 [GitHub Actions](https://docs.github.com/en/actions) 实现自动化构建与 NPM 发布。对应的构建脚本在 [.github/workflows/publish.yml](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs/blob/main/.github/workflows/publish.yml) 中
+
+触发条件（通过 GitHub release 触发）：
+```text
+on:
+  release:
+    types: [published]
+```
+
+构建脚本：
+```text
+  - run: npm install
+  - run: npm run build
+  - run: npm publish
+```
+
+NPM 发布的 Token，采用钉钉开放平台公共账号创建的 Access Token（通过 [GitHub secrets](https://docs.github.com/actions/security-guides/encrypted-secrets) 管理）：
+```text
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## 相关链接
+
+* [GitHub Actions documentation](https://docs.github.com/en/actions)
+* [Using secrets in GitHub Actions](https://docs.github.com/actions/security-guides/encrypted-secrets)
+* 该项目的构建脚本为：[.github/workflows/publish.yml](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs/blob/main/.github/workflows/publish.yml)

docs/explore/tutorials/stream/event/nodejs/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Node.js",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/explore/tutorials/stream/event/nodejs/build-listener.md

@@ -0,0 +1,119 @@
+---
+sidebar_position: 3
+---
+
+# 3. 开发事件订阅服务
+
+在本章节中，将会介绍如何用 Go 开发一个事件订阅服务，接收钉钉平台推送的变更通知。
+
+本教程的完整代码可以在 [GitHub 仓库](https://github.com/open-dingtalk/dingtalk-tutorial-go)中获取。
+
+## 创建 Go 模块
+
+```shell
+mkdir event_chat_update
+cd event_chat_update
+npm init -y
+npm install dingtalk-stream-sdk-nodejs commander
+npm install --save-dev typescript ts-node
+```
+
+## 安装依赖
+
+```shell
+go get github.com/open-dingtalk/dingtalk-stream-sdk-go
+```
+
+## 开发事件订阅服务
+
+在 go.mod 相同的目录下，创建 `event_handler.go` 文件，文件内容如下：
+
+```go title="event_handler.go" {13-32} showLineNumbers
+package main
+
+import (
+	"context"
+	"flag"
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/client"
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/event"
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/logger"
+	"github.com/open-dingtalk/dingtalk-stream-sdk-go/payload"
+	"time"
+)
+
+func OnEventReceived(_ context.Context, df *payload.DataFrame) (*payload.DataFrameResponse, error) {
+	eventHeader := event.NewEventHeaderFromDataFrame(df)
+	if eventHeader.EventType != "chat_update_title" {
+		// ignore events not equals `chat_update_title`; 忽略`chat_update_title`之外的其他事件；
+		// 该示例仅演示 chat_update_title 类型的事件订阅；
+		return event.NewSuccessResponse()
+	}
+
+	logger.GetLogger().Infof("received event, delay=%s, eventType=%s, eventId=%s, eventBornTime=%d, eventCorpId=%s, eventUnifiedAppId=%s, data=%s",
+		time.Duration(time.Now().UnixMilli()-eventHeader.EventBornTime)*time.Millisecond,
+		eventHeader.EventType,
+		eventHeader.EventId,
+		eventHeader.EventBornTime,
+		eventHeader.EventCorpId,
+		eventHeader.EventUnifiedAppId,
+		df.Data)
+	// put your code here; 可以在这里添加你的业务代码，处理事件订阅的业务逻辑；
+
+	return event.NewSuccessResponse()
+}
+
+func main() {
+	var clientId, clientSecret string
+	flag.StringVar(&clientId, "client_id", "", "your-client-id, AppKey or SuiteKey")
+	flag.StringVar(&clientSecret, "client_secret", "", "your-client-secret, AppSecret or SuiteSecret")
+	flag.Parse()
+	if len(clientId) == 0 || len(clientSecret) == 0 {
+		panic("command line options --client_id and --client_secret required")
+	}
+
+	logger.SetLogger(logger.NewStdTestLogger())
+
+	cli := client.NewStreamClient(client.WithAppCredential(client.NewAppCredentialConfig(clientId, clientSecret)))
+	cli.RegisterAllEventRouter(OnEventReceived)
+
+	err := cli.Start(context.Background())
+	if err != nil {
+		panic(err)
+	}
+
+	defer cli.Close()
+
+	select {}
+}
+```
+
+以上不超过 60 行的代码实现了这些能力：
+1. 通过命令行参数读取 Client ID 和 Client Secret 选项
+2. 通过 Client ID 和 Client Secret 创建 Stream Client
+3. 在 Stream Client 中注册事件推送的监听服务，实现变更通知的接收能力
+4. 在事件回调方法中，通过日志记录变更通知的消息内容，你可以可以改造这段代码，将变更通知写入自己的数据库中
+
+## 运行事件订阅服务
+
+通过以下命令可以运行你的事件订阅服务，当看到这样的日志输出时候表示运行成功 `[INFO] connect success, sessionId=[...]`
+”
+
+```shell
+go mod tidy
+go run event_handler.go --client_id="your-client-id" --client_secret="your-client-secret"
+```
+
+:::caution 注意事项
+务必将以上命令中"your-client-id"和"your-client-secret"替换成实际的值后再运行，否则无法成功建立连接。Client ID 和 Client Secret 可以通过[步骤二: 创建应用文档](create-app)获取。
+:::
+
+至此，你已成功完成事件订阅服务开发和部署。接下来可以在[钉钉开发者后台](https://open-dev.dingtalk.com)勾选需要订阅的事件类型，然后体验整个接收流程。
+
+:::info 说明
+如果你开发过钉钉聊天机器人的消息接收，就可以知道在聊天机器人代码中，需要指定订阅的 Topic，而事件订阅的代码中没有指定 Topic。原因是钉钉事件订阅平台的事件类型（Topic）是通过网页形式（在开发者后台）勾选，而不是通过代码方式指定 Topic。
+接下来的文档会提供指引，介绍如何在开发者后台勾选需要订阅的事件类型（Topic）。
+:::
+
+## 相关链接
+
+* [GitHub 上示例代码](https://github.com/open-dingtalk/dingtalk-tutorial-go)

docs/explore/tutorials/stream/event/nodejs/create-app.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+---
+
+# 2. 创建应用
+
+在本章节，将会介绍如何在钉钉[开发者后台](https://open-dev.dingtalk.com)创建一个应用。包括以下内容：
+1. 创建应用
+2. 获取应用凭证，即 Client ID 和 Client Secret
+
+## 创建应用
+
+1. 在浏览器中，进入**[开发者后台](https://open-dev.dingtalk.com)**，登录钉钉账号，选择开发组织，进入应用开发平台。
+2. 点击网页顶部菜单栏中的“**应用开发**”，进入应用管理。*注意：如果提示没有权限无法进入应用管理，可以在[这篇文档](/docs/explore/portal/grant-admin)中获得帮助*。
+3. **创建应用**。点击右上角“创建应用“，然后在弹出的对话框中，填写“**应用名称**”和“**应用描述**”即可。
+    1. 除应用名称和描述之外，其他选项采用默认值即可
+    2. (可选)你也可以为自己应用上传一个酷炫的应用图标
+    3. 注意：应用名称和描述必须符合当地法律法规要求，否则可能无法通过申请或者创建的应用无法正常使用
+    4. 创建应用操作如下：<br />![创建应用](/img/explore/stream/bot/create-app.jpg)
+       :::info 提示信息
+       钉钉开放平台全新升级后，采用“**以应用为中心**”的理念构建 PaaS 开放能力。包括工作台网页应用、机器人、酷应用等，都作为应用扩展能力的形式来开放。<br />
+       因此，以前跟应用并列的“机器人”将逐渐退出历史舞台。不要选择“钉钉应用”并列的“机器人”入口来创建，而是先创建“钉钉应用”，然后进入创建的应用，在应用内创建应用的机器人扩展。
+       :::
+4. **获取应用凭证**。完成以上步骤成功创建应用之后，进入应用详情页，在左侧导航中，点击“应用信息”，可以查看到应用凭证信息。
+    1. 可以点击复制后保存 Client ID（即 AppKey）和 Client Secret（即 AppSecret），用于后续的代码开发；
+    2. 关于 Client ID 和 Client Secret 命名<br />
+       :::info 提示信息
+       钉钉在未来的升级中，将逐渐采用统一的 OAuth 术语描述相关概念，减少概念混淆。<br />
+       原 AppKey 和 SuiteKey 逐渐统一成 Client ID。<br />
+       原 AppSecret 和 SuiteSecret 逐渐统一成 Client Secret。<br />
+       在很长一段的过渡期内，相关控制台页面和文档将会提供命名变更提示，帮助开发者理解这个变化。
+       :::
+
+至此，你已成功完成应用的创建，可以在后续的章节中学习如何开发事件订阅的代码。
+
+## 相关链接
+
+* [钉钉开发者后台](https://open-dev.dingtalk.com)

docs/explore/tutorials/stream/event/nodejs/intro.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+---
+
+# 1. 介绍
+
+本文以及接下来的步骤指引，介绍如何订阅钉钉平台的事件变更通知。
+
+## 功能
+
+通过这个教程，你可以学会
+
+1. 创建钉钉应用，配置 Stream 模式的事件订阅
+2. 开发事件订阅的处理代码，接收钉钉平台推送的事件推送消息
+
+## 准备工作
+
+1. 钉钉账号，获得开发者权限。关于开发者权限，你可以通过[这篇文章](/docs/explore/portal/grant-admin)获得相关操作指南
+2. [Node.js](https://nodejs.org/en/download/) and [npm](https://www.npmjs.com/package/npm) 开发环境
+
+:::tip
+相关代码在 Node.js 18.12.1 版本中通过了测试。在旧版本中通常也是可以工作的，但是未经过测试，推荐采用最新稳定版本。
+:::
+
+## 相关链接
+
+* [官方文档：事件订阅 - 配置 Stream 推送](https://open.dingtalk.com/document/orgapp/stream)