annict.jsドキュメント

# [annict.js](https://github.com/nukosuke/annict.js) [![npm version](https://badge.fury.io/js/annict.svg)](https://badge.fury.io/js/annict) [![Bower version](https://badge.fury.io/bo/annict.svg)](https://badge.fury.io/bo/annict)

アニメ視聴記録サービス[Annict](https://annict.com/)のAPIクライアントライブラリ、annict.jsのドキュメントです。
&raquo; [リファレンスドキュメントはこちら](https://nukosuke.github.io/annict.js/)

# はじめに
annict.jsはアニメ視聴記録サービスAnnictのAPIをNode.jsから利用するためのクライアントライブラリです。
APIの仕様については[公式ドキュメント](https://docs.annict.com/ja/api/)を参照してください。

# インストール

## Node, webpack, browserify
```shell-session
npm install annict --save
```

```js
var Annict = require('annict').default;
var annict = new Annict();
```

## ブラウザ
```shell-session
bower install annict --save
```

```html
<body>
    <script type='text/javascript'>
        var access_token = '[アクセストークン]'; //サーバ側で埋め込む
    </script>

    ...

    <script type='text/javascript' src='/js/annict.min.js'></script>
    <script type='text/javascript'>
        var annict = new Annict();
        ...
    </script>
</body>
```

# API
各APIにアクセスする方法です。
一部APIは書き込み権限を必要としますので`/oauth/token/info`を利用してトークンが`write`スコープを持っているか確認してください。

## 認証
アプリケーションに対して認可を行い、アクセストークンを取得します。
Annict APIは[OAuth 2.0](https://openid-foundation-japan.github.io/rfc6749.ja.html)に基づいて認可を行います。

- 公式ドキュメント - https://annict.wikihub.io/wiki/api/authentication

### 認証ページへのリダイレクト
※ このメソッドはNode.jsではサポートしていません

```js
annict.OAuth.authorize(
    client_id    : CLIENT_ID,
    response_type: 'code',
    redirect_uri : 'urn:ietf:wg:oauth:2.0:oob',
    scope        : ['read', 'write'] 
);
```

### アクセストークンの取得
※ このメソッドはブラウザではサポートしていません

```js
annict.OAuth.token(
    process.env.CLIENT_ID,       // client_id
    process.env.CLIENT_SECRET,   // client_secret
    'authorization_code',        // grant_type
    'urn:ietf:wg:oauth:2.0:oob', // redirect_uri
    CODE // https://api.annict.com/oauth/authorizeで取得したコード
)
.then(token => {
    annict.client.setHeader('Authorization', `Bearer ${token.access_token}`);
});
```

### トークン情報の取得
```js
annict.OAuth.info()
.then(info => {
    console.log(info.scopes); //=> ['read', 'write']
});
```

### トークンを失効させる
```js
annict.OAuth.revoke(token)
.then(console.log); //=> {}
```

## 作品検索
Annictデータベースに登録されているアニメ作品の検索ができます。

- 公式ドキュメント - https://annict.wikihub.io/wiki/api/works

```js
annict.Work.get({
    fileter_title: 'shirobako'
})
.then(res => {
    console.log(res.works);
});
```

## エピソード検索
作品のエピソード情報を取得することもできます。

- 公式ドキュメント - https://annict.wikihub.io/wiki/api/episodes

```js
annict.Episode.get({
    filter_ids: [1,2,3]
})
.then(res => {
    console.log(res.episodes);
});
```

## ユーザ
ユーザAPIでは認証ユーザに関連づく情報を取得します。
他のAnnictユーザの検索などはおそらくできません。

### ステータス更新
- 公式ドキュメント - https://annict.wikihub.io/wiki/api/me-statuses

このAPIを利用するには`write`スコープを持っているトークンが必要です。

```js
/**
 * kind := 'wanna_watch' 
 * | 'watching'
 * | 'watched'
 * | 'on_hold'
 * | 'stop_watching'
 * | 'no_select'
 */

annict.Me.Status.create({ work_id: 4636, kind: 'watching' })
.then(res => console.log(res.status)); //=> 204
```

### 記録
- 公式ドキュメント - https://annict.wikihub.io/wiki/api/me-records

me/records APIでは以下の操作が可能です。
自分の記録の取得は通常の `/records` APIにfilterをかけることで可能です。

- 新規記録の作成
- 記録の更新
- 記録の削除

```js
// 記録の作成
annict.Me.Record.create({
    episode_id     : 5013,
    comment        :'あぁ^～心がぴょんぴょんするんじゃぁ^～',
    share_twitter  :'true',
    share_facebook :'false'
})
.then(res => console.log(res.id)); //=> 1016


// 記録の更新
annict.Me.Record.update({
    id             : 1016,
    rating         : 5.0,
})
.then(res => console.log(res.rating)); //=> 5.0


// 記録の削除
annict.Me.Record.delete( 1016 )
.then(res => console.log(res.status)); //=> 204
```

### 作品取得
ユーザに関連する作品を取得することができます。例えば今視聴中の作品一覧を取得する場合は次のようになります。

- 公式ドキュメント - https://annict.wikihub.io/wiki/api/me-works

```js
annict.Me.Work.get({
    filter_status: 'watching'
})
.then(res => {
    console.log(res.works);
});
```

### 放送予定取得
放送予定を取得することができます。

- 公式ドキュメント - https://annict.wikihub.io/wiki/api/me-programs

```js
annict.Me.Program.get({
    sort_started_at: 'desc',
    filter_started_at_gt: '2016/05/05 02:00'
})
.then(res => {
    console.log(res.programs);
});
```