Merge pull request #25 from seymourtang/feature/convoai

feat:Add support for convo AI service

Author: seymourtang

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 repos:
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.21.2
+    rev: v8.24.0
     hooks:
       - id: gitleaks

README.md

@@ -9,35 +9,37 @@
 <img alt="GitHub Issues or Pull Requests" src="https://img.shields.io/github/issues-pr/AgoraIO-Community/agora-rest-client-go">
 </p>
 
-`agora-rest-client-go`是用Go语言编写的一个开源项目，专门为 Agora REST API设计。它包含了 Agora 官方提供的REST API接口的包装和内部实现，可以帮助开发者更加方便的集成服务端Agora REST API。
+English | [简体中文](./README_ZH.md)
 
-> 注意： 该SDK经过一些测试以确保其基本功能正常运作。然而，由于软件开发的复杂性，我们无法保证它是完全没有缺陷的。
->
->该SDK目前可能存在一些潜在的BUG或不稳定性。我们鼓励社区的开发者和用户积极参与，共同改进这个项目。
-
-## 特性
-* 封装了Agora REST API的请求和响应处理，简化与Agora REST API 的通信流程
-* 当遇到 DNS 解析失败、网络错误或者请求超时等问题的时候，提供了自动切换最佳域名的能力，以保障请求 REST API 服务的可用性
-* 提供了易于使用的API，可轻松地实现调用 Agora REST API 的常见功能，如开启云录制、停止云录制等
-* 基于Go语言，具有高效性、并发性和可扩展性
-
-## 支持的服务
-* [云端录制 Cloud Recording ](./services/cloudrecording/README.md)
-* [云端转码 Cloud Transcoder](./services/cloudtranscoder/README.md)
-
-## 环境准备
-* [Go 1.18 或以上版本](https://go.dev/)
-* 在声网 [Console 平台](https://console.shengwang.cn/)申请的 App ID 和 App Certificate
-* 在声网 [Console 平台](https://console.shengwang.cn/)的 Basic Auth 认证信息
-* 在声网 [Console 平台](https://console.shengwang.cn/)开启相关的服务能力
-
-## 安装
-使用以下命令从 GitHub 安装依赖：
+`agora-rest-client-go` is an open-source project written in Go, specifically designed for the Agora REST API. It includes wrappers and internal implementations of the official Agora REST API interfaces, making it easier for developers to integrate the server-side Agora REST API.
+
+> [!IMPORTANT]
+This SDK has undergone some testing to ensure its basic functionality works correctly. However, due to the complexity of software development, we cannot guarantee it is completely free of defects. We encourage community developers and users to actively participate and help improve this project.
+
+## Features
+* Encapsulates the request and response handling of the Agora REST API, simplifying the communication process with the Agora REST API.
+* Provides automatic switching to the best domain in case of DNS resolution failure, network errors, or request timeouts, ensuring the availability of the REST API service.
+* Offers easy-to-use APIs to easily implement common functions of the Agora REST API, such as starting and stopping cloud recording.
+* Based on Go language, it is efficient, concurrent, and scalable.
+
+## Supported Services
+* [Cloud Recording](./services/cloudrecording/README.md)
+* [Cloud Transcoder](./services/cloudtranscoder/README.md)
+* [Conversational AI Engine](./services/convoai/README.md)
+
+## Environment Setup
+* [Go 1.18 or later](https://go.dev/)
+* App ID and App Certificate obtained from the [Agora Console](https://console.shengwang.cn/)
+* Basic Auth credentials from the [Agora Console](https://console.shengwang.cn/)
+* Enable the relevant service capabilities on the [Agora Console](https://console.shengwang.cn/)
+
+## Installation
+Install the dependency from GitHub using the following command:
 ```shell
 go get -u github.com/AgoraIO-Community/agora-rest-client-go
 ```
-## 使用示例
-以调用云录制服务为例：
+## Usage Example
+Here is an example of calling the cloud recording service:
 
 ```go
 package main
@@ -191,32 +193,32 @@ func main() {
 }
 
 ```
-更多的示例可在[Example](./examples) 查看
+For more examples, see [Example](./examples).
 
-## 集成遇到困难，该如何联系声网获取协助
+## How to Contact Agora for Assistance if You Encounter Difficulties
 
-> 方案1：如果您已经在使用声网服务或者在对接中，可以直接联系对接的销售或服务
+> Option 1: If you are already using Agora services or are in the process of integration, you can directly contact your sales or service representative.
 >
-> 方案2：发送邮件给 [[email protected]](mailto:[email protected]) 咨询
+> Option 2: Send an email to [[email protected]](mailto:[email protected]) for consultation.
 >
-> 方案3：扫码加入我们的微信交流群提问
+> Option 3: Scan the QR code to join our WeChat group for questions.
 >
 > <img src="https://download.agora.io/demo/release/SDHY_QA.jpg" width="360" height="360">
 ---
 
-## 贡献
-本项目欢迎并接受贡献。如果您在使用中遇到问题或有改进建议，请提出issue或向我们提交Pull Request。
+## Contribution
+This project welcomes and accepts contributions. If you encounter any issues or have suggestions for improvements, please open an issue or submit a Pull Request.
 
-# SemVer 版本规范
-本项目使用语义化版本号规范 (SemVer) 来管理版本。格式为 MAJOR.MINOR.PATCH。
+# SemVer Versioning
+This project uses Semantic Versioning (SemVer) to manage versions. The format is MAJOR.MINOR.PATCH.
 
-* MAJOR 版本号表示不向后兼容的重大更改。
-* MINOR 版本号表示向后兼容的新功能或增强。
-* PATCH 版本号表示向后兼容的错误修复和维护。
-有关详细信息，请参阅 [语义化版本](https://semver.org/lang/zh-CN/) 规范。
+* MAJOR version indicates incompatible changes.
+* MINOR version indicates backward-compatible new features or enhancements.
+* PATCH version indicates backward-compatible bug fixes and maintenance.
+For more details, please refer to the [Semantic Versioning](https://semver.org) specification.
 
-## 参考
-* [Agora API 文档](https://doc.shengwang.cn/)
+## References
+* [Agora API Documentation](https://doc.shengwang.cn/)
 
-## 许可证
-该项目使用MIT许可证，详细信息请参阅LICENSE文件。
+## License
+This project is licensed under the MIT License. For more details, please refer to the LICENSE file.

README_ZH.md

@@ -0,0 +1,224 @@
+# Agora REST Client for Go
+<p>
+<img alt="GitHub License" src="https://img.shields.io/github/license/AgoraIO-Community/agora-rest-client-go">
+<a href="https://pkg.go.dev/github.com/AgoraIO-Community/agora-rest-client-go"><img src="https://pkg.go.dev/badge/github.com/AgoraIO-Community/agora-rest-client-go.svg" alt="Go Reference"></a>
+<a href="https://github.com/AgoraIO-Community/agora-rest-client-go/actions/workflows/go.yml"><img src="https://github.com/AgoraIO-Community/agora-rest-client-go/actions/workflows/go.yml/badge.svg" alt="Go Actions"></a>
+<a href="https://github.com/AgoraIO-Community/agora-rest-client-go/actions/workflows/gitee-sync.yml"><img alt="gitee-sync" src="https://github.com/AgoraIO-Community/agora-rest-client-go/actions/workflows/gitee-sync.yml/badge.svg?branch=main"></a>
+<img alt="GitHub go.mod Go version" src="https://img.shields.io/github/go-mod/go-version/AgoraIO-Community/agora-rest-client-go">
+<img alt="GitHub" src="https://img.shields.io/github/v/release/AgoraIO-Community/agora-rest-client-go">
+<img alt="GitHub Issues or Pull Requests" src="https://img.shields.io/github/issues-pr/AgoraIO-Community/agora-rest-client-go">
+</p>
+
+ [English](./README.md) | 简体中文
+
+`agora-rest-client-go`是用Go语言编写的一个开源项目，专门为 Agora REST API设计。它包含了 Agora 官方提供的REST API接口的包装和内部实现，可以帮助开发者更加方便的集成服务端Agora REST API。
+
+> [!IMPORTANT]
+该SDK经过一些测试以确保其基本功能正常运作。然而，由于软件开发的复杂性，我们无法保证它是完全没有缺陷的，我们鼓励社区的开发者和用户积极参与，共同改进这个项目。
+
+## 特性
+* 封装了Agora REST API的请求和响应处理，简化与Agora REST API 的通信流程
+* 当遇到 DNS 解析失败、网络错误或者请求超时等问题的时候，提供了自动切换最佳域名的能力，以保障请求 REST API 服务的可用性
+* 提供了易于使用的API，可轻松地实现调用 Agora REST API 的常见功能，如开启云录制、停止云录制等
+* 基于Go语言，具有高效性、并发性和可扩展性
+
+## 支持的服务
+* [云端录制 Cloud Recording](./services/cloudrecording/README.md)
+* [云端转码 Cloud Transcoder](./services/cloudtranscoder/README.md)
+* [对话式 AI 引擎 Conversationsal AI Engine](./services/convoai/README_ZH.md)
+
+## 环境准备
+* [Go 1.18 或以上版本](https://go.dev/)
+* 在声网 [Console 平台](https://console.shengwang.cn/)申请的 App ID 和 App Certificate
+* 在声网 [Console 平台](https://console.shengwang.cn/)的 Basic Auth 认证信息
+* 在声网 [Console 平台](https://console.shengwang.cn/)开启相关的服务能力
+
+## 安装
+使用以下命令从 GitHub 安装依赖：
+```shell
+go get -u github.com/AgoraIO-Community/agora-rest-client-go
+```
+## 使用示例
+以调用云录制服务为例：
+
+```go
+package main
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/AgoraIO-Community/agora-rest-client-go/agora"
+	"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
+	"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
+	agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
+	"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording"
+	cloudRecordingAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/api"
+	"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/scenario/mixrecording"
+)
+
+const (
+	appId    = "<your appId>"
+	cname    = "<your cname>"
+	uid      = "<your uid>"
+	username = "<the username of basic auth credential>"
+	password = "<the password of basic auth credential>"
+	token    = "<your token>"
+)
+
+var storageConfig = &cloudRecordingAPI.StorageConfig{
+	Vendor:    0,
+	Region:    0,
+	Bucket:    "",
+	AccessKey: "",
+	SecretKey: "",
+	FileNamePrefix: []string{
+		"recordings",
+	},
+}
+
+func main() {
+	// Initialize Agora Config
+	config := &agora.Config{
+		AppID:      appId,
+		Credential: auth.NewBasicAuthCredential(username, password),
+		// Specify the region where the server is located. Options include CN, EU, AP, US.
+		// The client will automatically switch to use the best domain based on the configured region.
+		DomainArea: domain.CN,
+		// Specify the log output level. Options include DebugLevel, InfoLevel, WarningLevel, ErrLevel.
+		// To disable log output, set logger to DiscardLogger.
+		Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
+	}
+
+	// Initialize the cloud recording service client
+	cloudRecordingClient, err := cloudrecording.NewClient(config)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Call the Acquire API of the cloud recording service client
+	acquireResp, err := cloudRecordingClient.MixRecording().
+		Acquire(context.TODO(), cname, uid, &mixrecording.AcquireMixRecodingClientRequest{})
+	// Handle non-business errors
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Handle business response
+	if acquireResp.IsSuccess() {
+		log.Printf("acquire success:%+v\n", acquireResp)
+	} else {
+		log.Fatalf("acquire failed:%+v\n", acquireResp)
+	}
+
+	// Call the Start API of the cloud recording service client
+	resourceId := acquireResp.SuccessRes.ResourceId
+	startResp, err := cloudRecordingClient.MixRecording().
+		Start(context.TODO(), resourceId, cname, uid, &mixrecording.StartMixRecordingClientRequest{
+			Token: token,
+			RecordingConfig: &cloudRecordingAPI.RecordingConfig{
+				ChannelType:  1,
+				StreamTypes:  2,
+				MaxIdleTime:  30,
+				AudioProfile: 2,
+				TranscodingConfig: &cloudRecordingAPI.TranscodingConfig{
+					Width:            640,
+					Height:           640,
+					FPS:              15,
+					BitRate:          800,
+					MixedVideoLayout: 0,
+					BackgroundColor:  "#000000",
+				},
+				SubscribeAudioUIDs: []string{
+					"#allstream#",
+				},
+				SubscribeVideoUIDs: []string{
+					"#allstream#",
+				},
+			},
+			RecordingFileConfig: &cloudRecordingAPI.RecordingFileConfig{
+				AvFileType: []string{
+					"hls",
+					"mp4",
+				},
+			},
+			StorageConfig: storageConfig,
+		})
+	// Handle non-business errors
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Handle business response
+	if startResp.IsSuccess() {
+		log.Printf("start success:%+v\n", startResp)
+	} else {
+		log.Fatalf("start failed:%+v\n", startResp)
+	}
+
+	sid := startResp.SuccessResponse.Sid
+	// Query
+	for i := 0; i < 6; i++ {
+		queryResp, err := cloudRecordingClient.MixRecording().
+			QueryHLSAndMP4(context.TODO(), resourceId, sid)
+		// Handle non-business errors
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// Handle business response
+		if queryResp.IsSuccess() {
+			log.Printf("query success:%+v\n", queryResp)
+		} else {
+			log.Printf("query failed:%+v\n", queryResp)
+		}
+		time.Sleep(time.Second * 10)
+	}
+
+	// Call the Stop API of the cloud recording service client
+	stopResp, err := cloudRecordingClient.MixRecording().
+		Stop(context.TODO(), resourceId, sid, cname, uid, true)
+	// Handle non-business errors
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Handle business response
+	if stopResp.IsSuccess() {
+		log.Printf("stop success:%+v\n", stopResp)
+	} else {
+		log.Printf("stop failed:%+v\n", stopResp)
+	}
+}
+
+```
+更多的示例可在[Example](./examples) 查看
+
+## 集成遇到困难，该如何联系声网获取协助
+
+> 方案1：如果您已经在使用声网服务或者在对接中，可以直接联系对接的销售或服务
+>
+> 方案2：发送邮件给 [[email protected]](mailto:[email protected]) 咨询
+>
+> 方案3：扫码加入我们的微信交流群提问
+>
+> <img src="https://download.agora.io/demo/release/SDHY_QA.jpg" width="360" height="360">
+---
+
+## 贡献
+本项目欢迎并接受贡献。如果您在使用中遇到问题或有改进建议，请提出issue或向我们提交Pull Request。
+
+# SemVer 版本规范
+本项目使用语义化版本号规范 (SemVer) 来管理版本。格式为 MAJOR.MINOR.PATCH。
+
+* MAJOR 版本号表示不向后兼容的重大更改。
+* MINOR 版本号表示向后兼容的新功能或增强。
+* PATCH 版本号表示向后兼容的错误修复和维护。
+有关详细信息，请参阅 [语义化版本](https://semver.org/lang/zh-CN/) 规范。
+
+## 参考
+* [Agora API 文档](https://doc.shengwang.cn/)
+
+## 许可证
+该项目使用MIT许可证，详细信息请参阅LICENSE文件。

agora/auth/basic.go

@@ -12,6 +12,17 @@ type BasicAuthCredential struct {
 // Ensure BasicAuthCredential implements Credential
 var _ Credential = (*BasicAuthCredential)(nil)
 
+// @brief Create a new BasicAuthCredential instance
+//
+// @note Customer ID and customer secret obtained from the Agora console, used for HTTP basic authentication
+//
+// @param username Customer ID obtained from the Agora console
+//
+// @param password Customer secret obtained from the Agora console
+//
+// @return Returns the BasicAuthCredential instance
+//
+// @since v0.7.0
 func NewBasicAuthCredential(username string, password string) *BasicAuthCredential {
 	return &BasicAuthCredential{
 		username: username,

agora/config.go

@@ -9,10 +9,24 @@ import (
 )
 
 type Config struct {
-	AppID       string
+	// Agora AppID
+	AppID string
+	// Timeout for HTTP requests
 	HttpTimeout time.Duration
-	Credential  auth.Credential
+	// Credential for accessing the Agora service.
+	//
+	// Available credential types:
+	//
+	//  - BasicAuthCredential: See auth.NewBasicAuthCredential for details
+	Credential auth.Credential
 
+	// Domain area for the REST Client. See domain.Area for details.
 	DomainArea domain.Area
-	Logger     log.Logger
+
+	// Logger for the REST Client
+	//
+	// Implement the log.Logger interface in your project to output REST Client logs to your logging component.
+	//
+	// Alternatively, you can use the default logging component. See log.NewDefaultLogger for details.
+	Logger log.Logger
 }