feat: SDK 3.0.0

rongcloud · Mar 13, 2018 · e41ba56 · e41ba56
1 parent b6c2e50
commit e41ba56
Show file tree

Hide file tree

Showing 214 changed files with 59,300 additions and 2,068 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
-node_modules
+**/node_modules
+coverage
 .idea
 .DS_Store
+**/_book
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 融云 Rong Cloud
+Copyright (c) 2018 融云 Rong Cloud
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,91 +1,52 @@
-The RongCloud Server SDK
-------------------------
+### Server SDK
 
-[Rong Cloud](http://rongcloud.cn) is committed to providing cloud-based instant messaging services for Internet and Mobile Internet developers. It enables developers to quickly integrate instant messaging capabilities with applications without any hardware installation requirements.
+#### 初始化
 
-The server SDK is a wrapper of all the https API calls, which could be found [here](http://www.rongcloud.cn/docs/server.html)
-
-
-## Install
-
-```bash
-$ npm install rongcloud-sdk
 ```
-
-## Init
-
-```js
-var rongcloudSDK = require( 'rongcloud-sdk' );
-rongcloudSDK.init( 'APP_KEY', 'APP_SECRET' );
+npm install rongcloud-sdk
 ```
 
-## Usage
-
-
-```js
-rongcloudSDK.user.getToken( '0001', 'Lance', 'http://files.domain.com/avatar.jpg', function( err, resultText ) {
-  if( err ) {
-    // Handle the error
-  }
-  else {
-    var result = JSON.parse( resultText );
-    if( result.code === 200 ) {
-      //Handle the result.token
-    }
-  }
-} );
-
-```
+#### 使用
 
-## Asking for a xml format response
+以注册用户为例
 
 ```js
-rongcloudSDK.user.getToken( '0001', 'Lance', 'http://files.domain.com/avatar.jpg', 'xml', function( err, resultText ) {
-  if( err ) {
-    // Handle the error
-  }
-  else {
-    // Handle the xml string, since Node.JS doesn't provide a native xml object, you have to handle it by yourself.
-  }
-} );
+var RongSDK = require('rongcloud-sdk')({
+    appkey: '8luwapucoil',
+    secret: 'y0iyjl4h3LWz'
+});
+
+// API 文档: http://www.rongcloud.cn/docs/server/sdk/user/user.html#register
+var User = RongSDK.User;
+var user = {
+	id: 'ujadk90ha',
+	name: 'Maritn',
+	portrait: 'http://7xogjk.com1.z0.glb.clouddn.com/IuDkFprSQ1493563384017406982'
+};
+User.register(user).then(result => {
+	console.log(result);
+}, error => { 
+	console.log(error);
+});
 ```
 
-##  API Coverage
-The SDK covers all of the RongCloud APIs, including:
-
-[User](http://www.rongcloud.cn/docs/server.html#用户服务)
-
-[User block](http://www.rongcloud.cn/docs/server.html#用户封禁服务)
-
-[User blackList](http://www.rongcloud.cn/docs/server.html#用户黑名单服务)
+#### 文档
 
-[Message](http://www.rongcloud.cn/docs/server.html#消息发送服务)
+[API 文档](http://rongcloud.github.io/server-sdk-nodejs/docs)
 
-[Messsage routing](http://www.rongcloud.cn/docs/server.html#消息路由服务)
+[API 示例](./example)
 
-[Message history](http://www.rongcloud.cn/docs/server.html#消息历史记录服务)
+#### 单元测试
 
-[Group](http://www.rongcloud.cn/docs/server.html#群组服务)
+1、下载或克隆 `server-sdk-nodejs`
 
-[Chatroom](http://www.rongcloud.cn/docs/server.html#聊天室服务)
+2、进入项目 `server-sdk-nodejs` 目录
 
-The SDK API is designed to keep accordant with the http request path, with all the **"/"** replaced with **"."**, that is, for the https API:
+3、安装依赖 `npm install`
 
-`https://api.cn.rong.io/user/getToken`
+4、运行单元测试 `npm test`
 
-You can call 
+#### 声明
 
-`rongcloudSDK.user.getToken`
-
-
-## Testing
-Since most of the time the user won't be using the components for testing(they are async, underscore, mocha, should and xml2js), these components are obtained only in the npm test script( you can see the scripts for testing in package.json), for testing, just run:
-
-```bash
-$ npm install
-$ npm installTestModules
-$ npm test
-```
+3.0.0 版本 SDK API 不再向老版本兼容，老版本 SDK 可用但不再维护
 
-## License
-[MIT](LICENSE)
diff --git a/const/index.js b/const/index.js
diff --git a/const/result.js b/const/result.js
diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
@@ -0,0 +1,200 @@
+### 消息类型{#message}
+
+消息类型分两类 `内置消息类型`、`自定义消息类型`，内置消息类型定义了常用消息，例如 `文本消息`、`图片消息` 等，若内置消息无法满足业务需求，可以使用自定消息类型	
+
+#### 内置消息{#inner-message}
+
+##### 消息类型{#inner-message-type}
+
+##### 文本消息
+
+消息类型: `RC:TxtMsg`
+
+消息结构:
+
+| 属性   	 |	类型		| 必填	| 说明 							
+| :----------|:--------	|:-----	|:------------------------------
+|	content  |	string	|	是 	| 文本消息内容
+|	extra	 |	any		|	否 	| 附加信息，例如: 发送消息携带用户信息
+
+结构示例:
+
+```json
+{
+	"content": "你好 RongCloud!",
+	"extra": {
+		"id": "mndk90",
+		"name": "孙大圣"
+	}
+}
+```
+
+##### 图片消息
+
+消息类型: `RC:ImgMsg`
+
+消息结构:
+
+| 属性   	 |	类型		| 必填	| 说明 							
+| :----------|:--------	|:-----	|:------------------------------
+|	content  |	string	|	是 	| `jpg` 类型缩略图，格式为 Base64，不包含头信息 `data:image/jpg;base64,`
+|	imageUri |	string	|	是 	| 图片消息 URL
+|	extra	 |	any		|	否 	| 附加信息
+
+JSON 示例:
+
+```json
+{
+	"content": "iVBORw0KGgoAAAAN...5ErkJggg==",
+	"imageUri": "http://www.rongcloud.cn/avatar.jpg",
+	"extra": "附加信息"
+}
+```
+
+##### 语音消息
+
+消息类型: `RC:VcMsg`
+
+消息结构:
+
+| 属性   	 |	类型		| 必填	| 说明 							
+| :----------|:--------	|:-----	|:------------------------------
+|	content  |	string	|	是 	| 语音内容，格式为 Base64 类型的 AMR
+|	duration |	number	|	是 	| 语音时长，单位: 秒
+|	extra	 |	any		|	否 	| 附加信息
+
+结构示例:
+
+```json
+{
+	"content": "IyFBTVIKPJEXFr5me...5ErkJggg==",
+	"duration": 10,
+	"extra": "附加信息"
+}
+```
+
+##### 图文消息
+
+消息类型: `RC:ImgTextMsg`
+
+消息结构:
+
+| 属性   	 |	类型		| 必填	| 说明 							
+| :----------|:--------	|:-----	|:------------------------------
+|	title  	 |	string	|	是 	| 消息标题
+|	content  |	string	|	是 	| 概要
+|	imageUri |	stirng	|	是 	| 图片地址
+|	url	 	 |	string	|	是 	| 跳转路径
+|	extra	 |	any		|	否 	| 附加信息
+
+结构示例:
+
+```json
+{
+	"title": "RongCloud",
+	"content": "即时通讯",
+	"imageUri": "http://www.rongcloud.cn/1.jpg",
+	"url": "http://www.rongcloud.cn",
+	"extra": "附加信息"
+}
+```
+
+##### 文件消息
+
+消息类型: `RC:FileMsg`
+
+消息结构:
+
+| 属性   	 |	类型		| 必填	| 说明 							
+| :----------|:--------	|:-----	|:------------------------------
+|	name  	 |	string	|	是 	| 名称
+|	size 	 |	number	|	是 	| 大小，单位: 字节
+|	type	 |	stirng	|	是 	| 类型，文件后缀名，不包含 `.`
+|	fileUrl	 |	string	|	是 	| 文件地址
+|	extra	 |	any		|	否 	| 附加信息
+
+结构示例:
+
+```json
+{
+	"name": "user.md",
+	"size": 3014,
+	"type": "md",
+	"fileUrl": "http://www.rongcloud.com/user.md",
+	"extra": "附加信息"
+}
+```
+
+##### 位置消息
+
+消息类型: `RC:LBSMsg`
+
+消息结构:
+
+| 属性   	 |	类型		| 必填	| 说明 							
+| :----------|:--------	|:-----	|:------------------------------
+|	content  |	string	|	是 	| `jpg` 类型缩略图，格式为 Base64，不包含头信息 `data:image/jpg;base64,`
+|	latitude |	number	|	是 	| 经度
+|	longitude|	number	|	是 	| 纬度
+|	poi	 	 |	string	|	是 	| 位置信息
+|	extra	 |	any		|	否 	| 附加信息
+
+结构示例:
+
+```json
+{
+	"content": "/9j/4AAQSkZJRgABA...jUHg4p9aos//2Q==",
+	"latitude": 24.114,
+	"longitude": 334.221,
+	"poi": "北京市朝阳区北苑路北辰泰岳大厦",
+	"extra": "附加内容"
+}
+```
+
+##### Push 内容{#inner-message-push}
+
+中文 Push:
+
+| 消息   	 |	类型			| 单聊									|  群聊
+| :----------|:----------	|:--------------------------------------| :-------	
+| 文本消息	 |RC:TxtMsg		| 发送者: `content` 内容					| 群名: `content` 内容
+| 图片消息	 |RC:ImgMsg		| 发送者: [图片] 							| 群名: [图片]
+| 语音消息	 |RC:VcMsg		| 发送者: [语音] 							| 群名: [语音]
+| 图文消息	 |RC:ImgTextMsg	| 发送者: [图文] 							| 群名: [图文]
+| 文件消息	 |RC:FileMsg	| 发送者: [文件] 							| 群名: [文件]
+| 位置消息	 |RC:LBSMsg		| 发送者: [位置] 							| 群名: [位置]
+
+英文 Push:
+
+| 消息   	 |	类型			| 单聊									|  群聊
+| :----------|:----------	|:--------------------------------------| :-------	
+| 文本消息	 |RC:TxtMsg		| 发送者: `content` 内容					| 群名: `content` 内容
+| 图片消息	 |RC:ImgMsg		| 发送者: [Image] 						| 群名: [Image]
+| 语音消息	 |RC:VcMsg		| 发送者: [Voice] 						| 群名: [Voice]
+| 图文消息	 |RC:ImgTextMsg	| 发送者: [Rich Content] 				| 群名: [Rich Content]
+| 文件消息	 |RC:FileMsg	| 发送者: [File] 						| 群名: [File]
+| 位置消息	 |RC:LBSMsg		| 发送者: [Location] 					| 群名: [Location]
+
+#### 自定义消息{#custom-message}
+
+当内置消息类型无法满足业务需求是，可使用自定义消息实现业务
+
+##### 消息类型{#custom-message-type}
+
+`自定义消息` 类型名称无限制，对格式做 `前缀:名称` 约定，例如 `Mt:ChrmNotify`，消息题可按需求自定义
+
+例如需求:	 考试结束了，需要学生们发送成绩单，定义消息 `Stu:score` 属性有 `score` 
+
+结构示例:
+
+```json
+{
+	"score": {
+		"english": 95,
+		"physics": 96
+	}
+}
+```
+##### Push 内容{#custom-message-push}
+
+自定义消息默认无 Push， 若需要 Push 请设置`发送消息` 接口 `PushContent` 属性
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,25 @@
+#### 使用步骤
+
+##### 1、注册开发者，请移步 [开发者后台](https://developer.rongcloud.cn)
+
+##### 2、创建应用
+
+##### 3、获取 Appkey 、 Secret
+
+#### Server SDK{#server-sdk}
+
+各平台 SDK **源码**、**示例** 请移步: [Java](https://github.com/rongcloud/server-sdk-java)、 [Node](https://github.com/rongcloud/server-sdk-nodejs)
+
+#### SDK 使用指南
+
+<img src="http://www.rongcloud.cn/docs/assets/img/guide/archietecture@2x.png" width="600" height="500">
+
+>图解
+
+蓝色框表示应用服务器 (App Server)，用来处理业务数据，比如用户信息、群组关系等
+
+App Server 会使用到融云 Server SDK： [Java](https://github.com/rongcloud/server-sdk-java)、 [Node](https://github.com/rongcloud/server-sdk-nodejs)
+
+蓝色为应用（App），客户端发送消息使用，会用到各端 SDK: [iOS](http://www.rongcloud.cn/docs/ios.html#integration)、[Android](http://www.rongcloud.cn/docs/android.html#integration)、[Web](http://www.rongcloud.cn/docs/web.html#sdk)、[Desktop](http://www.rongcloud.cn/docs/desktop.html)
+
+绿色框表示融云服务器 (RongCloud Server) ，是消息通道，调用各端 SDK 发送消息即可