Skip to content

Commit

Permalink
fix: add documents and add shipjs, and add the headers field to `Ga…
Browse files Browse the repository at this point in the history 
…roonRestAPIError` (#2)
  • Loading branch information
@miyajan
miyajan authored Jun 29, 2020
1 parent 70dcb83 commit 28407e7
Show file tree
Hide file tree
Showing 11 changed files with 2,427 additions and 113 deletions.
22 changes: 0 additions & 22 deletions .github/workflows/publish.yml
View file

This file was deleted.

63 changes: 63 additions & 0 deletions .github/workflows/shipjs-manual-prepare.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
name: Ship js Manual Prepare
on:
issue_comment:
types: [created]
jobs:
manual_prepare:
if: |
github.event_name == 'issue_comment' &&
(github.event.comment.author_association == 'member' || github.event.comment.author_association == 'owner') &&
startsWith(github.event.comment.body, '@shipjs prepare')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2.3.1
with:
fetch-depth: 0
ref: master
- uses: actions/setup-node@v2.0.0
with:
node-version: 12.x
- run: |
if [ -f "yarn.lock" ]; then
yarn install
else
npm ci
fi
- run: |
git config --global user.email "github-actions[bot]@users.noreply.github.com"
git config --global user.name "github-actions[bot]"
- run: npm run release -- --yes --no-browse
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

create_done_comment:
if: success()
needs: manual_prepare
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v2.0.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: "@${{ github.actor }} `shipjs prepare` done"
})
create_fail_comment:
if: cancelled() || failure()
needs: manual_prepare
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v2.0.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: "@${{ github.actor }} `shipjs prepare` fail"
})
30 changes: 30 additions & 0 deletions .github/workflows/shipjs-trigger.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Ship js trigger
on:
pull_request:
types:
- closed
jobs:
build:
name: Release
runs-on: ubuntu-latest
if: github.event.pull_request.merged == true && startsWith(github.head_ref, 'releases/v')
steps:
- uses: actions/checkout@v2.3.1
with:
fetch-depth: 0
ref: master
- uses: actions/setup-node@v2.0.0
with:
node-version: 12.x
registry-url: "https://registry.npmjs.org"
- run: |
if [ -f "yarn.lock" ]; then
yarn install
else
npm ci
fi
npm run prerelease
- run: npx shipjs trigger
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
33 changes: 33 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Contributing Guide

## For Contributors

Thank you for your contribution!

### Setup

```sh
% cd garoon-rest
% npm install
```

### Test

```sh
% cd garoon-rest
% npm test
% npm run lint
```

## For Maintainers

### Merge

After you have approved a PR, please merge the PR using **Squash and merge** with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.

### Release

```
% cd garoon-rest
% npm run release
```
126 changes: 126 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,135 @@
# garoon-rest

[![npm version](https://badge.fury.io/js/%40miyajan%2Fgaroon-rest.svg)](https://badge.fury.io/js/%40miyajan%2Fgaroon-rest)

Rest API Client for Garoon

WIP.

## Installation

### 1. Install with `npm`

This library is distributed on `npm`.

```shell
npm install @miyajan/garoon-rest
```

You can then use `require` or `import` to import the library.

```javascript
// CommonJS
const { GaroonRestAPIClient } = require("@miyajan/garoon-rest");
// ES modules
import { GaroonRestAPIClient } from "@miyajan/garoon-rest";
```

### 2. UMD files (for browser environment)

This library also provides two Universal Module Definition (UMD) files:

- https://unpkg.com/@miyajan/garoon-rest@latest/umd/GaroonRestAPIClient.js
- minified one: https://unpkg.com/@miyajan/garoon-rest@latest/umd/GaroonRestAPIClient.min.js

After loading this, you can use `GaroonRestAPIClient` directly.
In Garoon customization, please add this URL in "JavaScript and CSS customization" setting.

NOTE: The UMD links are using the `latest` tag to point to the latest version of the library. This pointer is unstable, it shifts as we release new versions. You should consider pointing to a specific version, such as [`1.0.0`](https://unpkg.com/@miyajan/garoon-rest@1.0.0/umd/GaroonRestAPIClient.js).

## Usage

Here is a sample code that retrieves a schedule event.

```js
const client = new GaroonRestAPIClient({
baseUrl: "https://example.cybozu.com",
// Use password authentication
auth: {
username: process.env.GAROON_USERNAME,
password: process.env.GAROON_PASSWORD,
},
// Use OAuth token authentication
// auth: { oAuthToken: process.env.GAROON_OAUTH_TOKEN }

// Use session authentication if `auth` is omitted (in browser only)
});

client.schedule
.getEvent({ id: "1" })
.then((resp) => {
console.log(resp);
})
.catch((err) => {
console.log(err);
});
```

## Parameters for `GaroonRestAPIClient`

| Name | Type | Required | Description |
| -------------------------- | :--------------------------------------------------------------: | :-------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl | String | Conditionally<br />Required | The base URL for your Garoon environment.<br />It must start with `https`. (e.g. https://example.cybozu.com) <br />Required in Node.js environment. If you omit it in browser environment, `location.origin` will be used. |
| auth | Object | Conditionally<br />Required | The object for authentication. See [Authentication](#Authentication). |
| basicAuth | Object | | If your Garoon environment uses Basic authentication, please specify its username and password. |
| basicAuth.username | String | | The username of Basic authentication. |
| basicAuth.password | String | | The password of Basic authentication. |
| clientCertAuth | Object | | **This parameter is available only in Node.js environment.**<br />If your Garoon environment uses [Client Certificate authentication](https://jp.cybozu.help/general/en/admin/list_security/list_secureaccess/overview.html), please specify the certificate file and password. |
| clientCertAuth.pfx | [Buffer](https://nodejs.org/api/buffer.html#buffer_class_buffer) | | The [client certificate file](https://jp.cybozu.help/general/en/user/list_access/remote/webbrowser.html). Required, unless you specify `pfxFilePath`. |
| clientCertAuth.pfxFilePath | String | | The path to [client certificate file](https://jp.cybozu.help/general/en/user/list_access/remote/webbrowser.html). Required, unless you specify `pfx`. |
| clientCertAuth.password | String | | The password of client certificate. |
| proxy | Object | | **This parameter is available only in Node.js environment.**<br />If you use a proxy, please specify its configuration. |
| proxy.host | String | | The host of the proxy server. |
| proxy.port | Number | | The port of the proxy server. |
| proxy.auth | Object | | If the proxy server requires Basic authentication, please specify its username and password. |
| proxy.auth.username | String | | The username of Basic authentication for the proxy server. |
| proxy.auth.password | String | | The password of Basic authentication for the proxy server. |

### Authentication

The client supports three authentication methods:

1. [Password authentication](https://developer.cybozu.io/hc/ja/articles/360000503306-Garoon-REST-API%E3%81%AE%E5%85%B1%E9%80%9A%E4%BB%95%E6%A7%98#step2)
2. [OAuth authentication](https://developer.cybozu.io/hc/ja/articles/360015955171)
3. [Session authentication](https://developer.cybozu.io/hc/ja/articles/360000503306-Garoon-REST-API%E3%81%AE%E5%85%B1%E9%80%9A%E4%BB%95%E6%A7%98#step2)

The required parameters inside `auth` are different by the methods.
The client determines which method to use by passed parameters.

#### 1. Parameters for [Password authentication](https://developer.cybozu.io/hc/ja/articles/360000503306-Garoon-REST-API%E3%81%AE%E5%85%B1%E9%80%9A%E4%BB%95%E6%A7%98#step2)

| Name | Type | Required | Description |
| -------- | :----: | :------: | ----------- |
| username | String | Yes |
| password | String | Yes |

#### 2. Parameters for [OAuth authentication](https://developer.cybozu.io/hc/ja/articles/360015955171)

| Name | Type | Required | Description |
| ---------- | :----: | :------: | ------------------------------------------------------------------------------------------------------------------------ |
| oAuthToken | String | Yes | An OAuth access token you get through the [OAuth process flow](https://developer.cybozu.io/hc/ja/articles/360015955171). |

#### 3. [Session authentication](https://developer.cybozu.io/hc/ja/articles/360000503306-Garoon-REST-API%E3%81%AE%E5%85%B1%E9%80%9A%E4%BB%95%E6%A7%98#step2)

Supported in browser environment only.
If you omit `auth` parameter, the client uses Session authentication.

## Error Handling

See [Error Handling](https://github.com/miyajan/garoon-rest/tree/master/docs/errorHandling.md)

## References

- [Schedule](https://github.com/miyajan/garoon-rest/tree/master/docs/schedule.md)

## Contribution Guide

- [CONTRIBUTING.md](https://github.com/miyajan/garoon-rest/tree/master/CONTRIBUTING.md)

## License

- [MIT](https://github.com/miyajan/garoon-rest/tree/master/LICENSE)

## Disclaimer

This OSS is my own personal work and does not have any relationship with Cybozu Inc. or any other organization which I belong to.
14 changes: 14 additions & 0 deletions docs/errorHandling.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Error Handling

## GaroonRestAPIError

When the API request responds with a status code other than 200, the client raises [`GaroonRestAPIError`](../src/GaroonRestAPIError.ts).

[`GaroonRestAPIError`](../src/GaroonRestAPIError.ts) has the following properties:

| Name | Type | Description |
| --------- | :----: | ---------------------------------------------------------- |
| errorCode | String | The code of the error, to specify the type of error it is. |
| status | Number | The HTTP status of the response. |
| headers | Object | The HTTP headers of the response. |
| message | String | The error message. |
40 changes: 40 additions & 0 deletions docs/schedule.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Schedule

- [getEvent](#getevent)

## Overview

```ts
const client = new GaroonRestAPIClient();

(async () => {
try {
console.log(await client.schedule.getEvent({ id: "1" }));
} catch (error) {
console.log(error);
}
})();
```

- All methods are defined on the `schedule` property.
- This method returns a Promise object that is resolved with an object having properties in each `Returns` section.

## Methods

### getEvent

Get the contents of an event by specifying the event ID.

#### Parameters

| Name | Type | Required | Description |
| ---- | :--------------: | :------: | ------------- |
| id | Number or String | Yes | The event ID. |

#### Returns

See the example response in the `Reference`.

#### Reference

- https://developer.cybozu.io/hc/ja/articles/360000440583#step1
Loading

0 comments on commit 28407e7

Please sign in to comment.