Skip to content

Commit 4a24d35

Browse files
gxfang1985gxfang1985
committed
create rest-api-client-dingtalk-mp
1 parent 4db7990 commit 4a24d35

18 files changed

+12108
-2
lines changed

‎.eslintrc.js

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
module.exports = {
2+
extends: '@cybozu',
3+
globals: {
4+
dd: false
5+
},
6+
env: {
7+
jest: true
8+
},
9+
};

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
.idea
3+
coverage

‎LICENSE.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
MIT License
2+
3+
Copyright (c) 2020 Cybozu, Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
22+
23+
24+
Licenses for Third-Party Components
25+
26+
The following sections contain licensing information for libraries that
27+
we have included with the kintone-rest-api-client-wechat-mp.js.
28+
29+
**js-base64**
30+
31+
This product includes js-base64.
32+
33+
Copyright (c) 2014, Dan Kogai
34+
All rights reserved.
35+
36+
Redistribution and use in source and binary forms, with or without
37+
modification, are permitted provided that the following conditions are met:
38+
39+
* Redistributions of source code must retain the above copyright notice, this
40+
list of conditions and the following disclaimer.
41+
42+
* Redistributions in binary form must reproduce the above copyright notice,
43+
this list of conditions and the following disclaimer in the documentation
44+
and/or other materials provided with the distribution.
45+
46+
* Neither the name of {{{project}}} nor the names of its
47+
contributors may be used to endorse or promote products derived from
48+
this software without specific prior written permission.
49+
50+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
51+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
52+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
53+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
54+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
55+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
56+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
57+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
58+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
59+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
60+
61+
**qs**
62+
63+
This product includes qs.
64+
65+
BSD 3-Clause License
66+
67+
Copyright (c) 2014, Nathan LaFreniere and other [contributors](https://github.com/ljharb/qs/graphs/contributors)
68+
All rights reserved.
69+
70+
Redistribution and use in source and binary forms, with or without
71+
modification, are permitted provided that the following conditions are met:
72+
73+
1. Redistributions of source code must retain the above copyright notice, this
74+
list of conditions and the following disclaimer.
75+
76+
2. Redistributions in binary form must reproduce the above copyright notice,
77+
this list of conditions and the following disclaimer in the documentation
78+
and/or other materials provided with the distribution.
79+
80+
3. Neither the name of the copyright holder nor the names of its
81+
contributors may be used to endorse or promote products derived from
82+
this software without specific prior written permission.
83+
84+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
85+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
86+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
87+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
88+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
89+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
90+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
91+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
92+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
93+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md

+105-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,105 @@
1-
# rest-api-client-dingtalk-mp
2-
kintone REST API client for DingTalk Mini Program
1+
# kintone-rest-api-client-dingtalk-mp
2+
3+
[![npm version](https://badge.fury.io/js/%40kintone%2Frest-api-client-dingtalk-mp.svg)](https://badge.fury.io/js/%40kintone%2Frest-api-client-dingtalk-mp)
4+
5+
An API client for Kintone REST API, it is used in DingTalk Mini Program client.<br>
6+
It is based on [@kintone/rest-api-client@v1.2.0](https://github.com/kintone/js-sdk/tree/%40kintone/rest-api-client%401.2.0/packages/rest-api-client). <br>
7+
It wraps the functions of app, record and bulkRequest of "@kintone/rest-api-client", and develops the new functions of file.
8+
9+
## Requirement
10+
11+
- [DingTalk Developer Tool](https://ding-doc.dingtalk.com/doc#/kn6zg7/zunrdk) (The latest)<br>
12+
13+
## Usage
14+
15+
**Step 1**
16+
17+
Open DingTalk Developer Tool and create a new project. (Ref. [小程序IDE使用](https://ding-doc.dingtalk.com/doc#/dev/yqm3sq))
18+
19+
**Step 2**
20+
21+
Install with `npm`
22+
23+
```shell
24+
cd [your-project-directory]
25+
npm init -y
26+
npm install @kintone/rest-api-client-dingtalk-mp
27+
```
28+
29+
### Sample code
30+
31+
```js
32+
const {KintoneRestAPIClientDingTalkMP} = require('@kintone/rest-api-client-dingtalk-mp');
33+
const client = new KintoneRestAPIClientDingTalkMP({
34+
baseUrl: "https://example.cybozu.com",
35+
// Use password authentication
36+
auth: {
37+
username: process.env.KINTONE_USERNAME,
38+
password: process.env.KINTONE_PASSWORD,
39+
},
40+
// Use API token authentication
41+
// auth: { apiToken: process.env.KINTONE_API_TOKEN }
42+
});
43+
44+
client.record
45+
.getRecords({ app: "1" })
46+
.then((resp) => {
47+
console.log(resp.records);
48+
})
49+
.catch((err) => {
50+
console.log(err);
51+
});
52+
```
53+
54+
## Parameters for `KintoneRestAPIClientDingTalkMP`
55+
56+
| Name | Type | Required | Description |
57+
| -------------------------- | :--------------------------------------------------------------: | :-------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58+
| baseUrl | String | Required | The base URL for your Kintone environment.<br />It must start with `https`. (e.g. https://example.kintone.com) |
59+
| auth | Object | Required | The object for authentication. See [Authentication](#Authentication). |
60+
| guestSpaceId | Number or String | | The guest space ID. If you are dealing with apps that are in guest spaces, please specify this. |
61+
| basicAuth | Object | | If your Kintone environment uses Basic authentication, please specify its username and password. |
62+
| basicAuth.username | String | | The username of Basic authentication. |
63+
| basicAuth.password | String | | The password of Basic authentication. |
64+
65+
### Authentication
66+
67+
The client supports three authentication methods:
68+
69+
1. [Password authentication](https://developer.kintone.io/hc/en-us/articles/212495188#passwordAuth)
70+
2. [API token authentication](https://developer.kintone.io/hc/en-us/articles/212495188#APItokenAuth)
71+
72+
The required parameters inside `auth` are different by the methods.
73+
The client determines which method to use by passed parameters.
74+
75+
#### 1. Parameters for [Password authentication](https://developer.kintone.io/hc/en-us/articles/212495188#passwordAuth)
76+
77+
| Name | Type | Required | Description |
78+
| -------- | :----: | :------: | ----------------- |
79+
| username | String | Yes | User's login name |
80+
| password | String | Yes | User's password |
81+
82+
#### 2. Parameters for [API token authentication](https://developer.kintone.io/hc/en-us/articles/212495188#APItokenAuth)
83+
84+
| Name | Type | Required | Description |
85+
| -------- | :----------------: | :------: | ------------------------------------------------------- |
86+
| apiToken | String or String[] | Yes | You can pass multiple api tokens as an array of string. |
87+
88+
## References
89+
90+
- [File](docs/file.md)
91+
92+
The usage of following functions is not changed, you can refer to the doc of "@kintone/rest-api-client".<br>
93+
Pay attention to the class name, you should use KintoneRestAPIClientDingTalkMP in DingTalk. Refer to [Sample code](#sample-code).
94+
- [@kintone/rest-api-client/errorHandling](https://github.com/kintone/js-sdk/blob/%40kintone/rest-api-client%401.2.0/packages/rest-api-client/docs/errorHandling.md)
95+
- [@kintone/rest-api-client/record](https://github.com/kintone/js-sdk/blob/%40kintone/rest-api-client%401.2.0/packages/rest-api-client/docs/record.md)
96+
- [@kintone/rest-api-client/app](https://github.com/kintone/js-sdk/blob/%40kintone/rest-api-client%401.2.0/packages/rest-api-client/docs/app.md)
97+
- [@kintone/rest-api-client/bulkRequest](https://github.com/kintone/js-sdk/blob/%40kintone/rest-api-client%401.2.0/packages/rest-api-client/docs/bulkRequest.md)
98+
99+
## License
100+
101+
- [MIT](LICENSE.md)
102+
103+
## Copyright
104+
105+
Copyright(c) Cybozu, Inc.

‎babel.config.js

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
module.exports = {
2+
presets: [
3+
[
4+
'@babel/preset-env',
5+
{
6+
targets: {
7+
node: 'current',
8+
},
9+
},
10+
],
11+
],
12+
};

‎dist/kintone-rest-api-client-dingtalk-mp.js

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/file.md

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# File
2+
3+
- [uploadFile](#uploadFile)
4+
- [downloadFile](#downloadFile)
5+
6+
## Overview
7+
8+
```js
9+
const client = new KintoneRestAPIClientDingTalkMP({
10+
baseUrl: "https://example.cybozu.com",
11+
auth: {
12+
username: process.env.KINTONE_USERNAME,
13+
password: process.env.KINTONE_PASSWORD,
14+
}
15+
});
16+
17+
(async () => {
18+
const APP_ID = "1";
19+
const ATTACHMENT_FIELD_CODE = "Attachment";
20+
21+
const FILE = {
22+
name: "Hello.txt",
23+
data: "Hello World!"
24+
};
25+
26+
const filePath = `${dd.env.USER_DATA_PATH}/${FILE.name}`;
27+
28+
// Upload a file and attach it to a record
29+
const { fileKey } = await client.file.uploadFile({ filePath });
30+
const { id } = await client.record.addRecord({
31+
app: APP_ID,
32+
record: {
33+
[ATTACHMENT_FIELD_CODE]: {
34+
value: [{ fileKey }]
35+
}
36+
}
37+
});
38+
39+
// Download the attached file
40+
const { record } = await client.record.getRecord({
41+
app: APP_ID,
42+
id,
43+
});
44+
const { filePath } = await client.file.downloadFile({
45+
fileKey: record[ATTACHMENT_FIELD_CODE].value[0].fileKey
46+
});
47+
console.log(filePath);
48+
})();
49+
```
50+
51+
- All methods are defined on the `file` property.
52+
53+
## Methods
54+
55+
### uploadFile
56+
57+
Uploads a file to Kintone.
58+
59+
`uploadFile` returns a file key for the uploaded file.
60+
You can use the file key at the following place.
61+
62+
- Attachment field in an app
63+
- JavaScript and CSS customization settings of an app
64+
65+
#### Parameters
66+
67+
| Name | Type | Required | Description |
68+
| --------- | :----: | :------: | ----------------------|
69+
| filePath | String | Yes | The path to the file. |
70+
71+
#### Returns
72+
73+
`uploadFile` returns a Promise object that is resolved with an object having following properties.
74+
75+
| Name | Type | Description |
76+
| ------- | :----: | ---------------------------------- |
77+
| fileKey | String | The file key of the uploaded file. |
78+
79+
#### Reference
80+
81+
- https://ding-doc.dingtalk.com/doc#/dev/frd69q
82+
- https://developer.kintone.io/hc/en-us/articles/212494448
83+
84+
### downloadFile
85+
86+
Downloads files using a file key from kintone.
87+
88+
This is **NOT** the file key `uploadFile` returns.
89+
You can get the file key from the following place.
90+
91+
- Attachment field in an app
92+
- JavaScript and CSS customization settings of an app
93+
94+
#### Parameters
95+
96+
| Name | Type | Required | Description |
97+
| ---------- | :----: | :------: | ------------------------------------ |
98+
| fileKey | String | Yes | The file key of the downloaded file. |
99+
100+
#### Returns
101+
102+
`downloadFile` returns a Promise object that is resolved with the following value.
103+
104+
| Name | Type | Description |
105+
| ------------ | :----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106+
| filePath | String | Temporary file path. |
107+
108+
#### Reference
109+
110+
- https://ding-doc.dingtalk.com/doc#/dev/frd69q
111+
- https://developer.kintone.io/hc/en-us/articles/212494468

‎jest.config.js

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
module.exports = {
2+
clearMocks: true,
3+
rootDir: 'src',
4+
testPathIgnorePatterns: ['node_modules'],
5+
testEnvironment: 'node',
6+
transformIgnorePatterns: ['<rootDir>/node_modules/(?!(@kintone/rest-api-client)/)'],
7+
};

0 commit comments

Comments
 (0)