Sharkey/README.md

156 lines
5.2 KiB
Markdown
Raw Normal View History

2021-05-14 04:54:41 +02:00
# misskey.js
2021-05-16 17:07:01 +02:00
**Strongly-typed official Misskey SDK for browsers/Node.js.**
2021-06-12 15:50:45 +02:00
[![Test](https://github.com/misskey-dev/misskey.js/actions/workflows/test.yml/badge.svg)](https://github.com/misskey-dev/misskey.js/actions/workflows/test.yml)
2021-06-25 02:46:40 +02:00
[![codecov](https://codecov.io/gh/misskey-dev/misskey.js/branch/develop/graph/badge.svg?token=PbrTtk3nVD)](https://codecov.io/gh/misskey-dev/misskey.js)
2021-06-12 15:50:45 +02:00
2021-05-23 10:17:14 +02:00
[![NPM](https://nodei.co/npm/misskey-js.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/misskey-js)
2021-05-16 17:07:01 +02:00
JavaScript(TypeScript)用の公式MisskeySDKです。ブラウザ/Node.js上で動作します。
以下が提供されています:
- ユーザー認証
- APIリクエスト
- ストリーミング
- ユーティリティ関数
2021-07-07 16:23:34 +02:00
- Misskeyの各種型定義
2021-05-14 04:54:41 +02:00
2021-07-11 12:34:35 +02:00
対応するMisskeyのバージョンは12以上です。
2021-05-14 05:00:58 +02:00
## Install
2021-05-23 10:16:14 +02:00
```
npm i misskey-js
```
2021-05-14 05:00:58 +02:00
2021-05-14 04:54:41 +02:00
# Usage
2021-07-13 15:08:55 +02:00
インポートは以下のようにまとめて行えます。
``` ts
import * as Misskey from 'misskey-js';
```
便宜上、以後のコード例は上記のように`* as Misskey`としてインポートしている前提のものになります。
まとめてインポートを行うとTree-Shakingできなくなるので、適宜変更をおすすめします。
2021-05-16 11:30:42 +02:00
## Authenticate
todo
2021-05-14 04:54:41 +02:00
## API request
2021-07-11 12:33:21 +02:00
APIを利用する際は、利用するサーバーの情報とアクセストークンを与えて`APIClient`クラスのインスタンスを初期化し、そのインスタンスの`request`メソッドを呼び出してリクエストを行います。
2021-05-16 11:27:21 +02:00
``` ts
const cli = new Misskey.api.APIClient({
2021-05-23 05:15:28 +02:00
origin: 'https://misskey.test',
credential: 'TOKEN',
2021-05-16 11:27:21 +02:00
});
const meta = await cli.request('meta', { detail: true });
```
2021-05-14 04:54:41 +02:00
2021-07-11 12:33:21 +02:00
`request`の第一引数には呼び出すエンドポイント名、第二引数にはパラメータオブジェクトを渡します。レスポンスはPromiseとして返ります。
2021-05-14 04:54:41 +02:00
## Streaming
2021-07-11 12:29:04 +02:00
misskey.jsのストリーミングでは、二つのクラスが提供されます。
2021-07-11 12:33:21 +02:00
ひとつは、ストリーミングのコネクション自体を司る`Stream`クラスと、もうひとつはストリーミング上のチャンネルの概念を表す`Channel`クラスです。
2021-07-11 12:29:04 +02:00
ストリーミングを利用する際は、まず`Stream`クラスのインスタンスを初期化し、その後で`Stream`インスタンスのメソッドを利用して`Channel`クラスのインスタンスを取得する形になります。
2021-05-16 11:33:08 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
2021-05-23 06:34:36 +02:00
const mainChannel = stream.useChannel('main');
2021-05-16 11:33:08 +02:00
mainChannel.on('notification', notification => {
console.log('notification received', notification);
});
```
2021-05-14 05:00:10 +02:00
2021-07-11 12:18:27 +02:00
コネクションが途切れても自動で再接続されます。
2021-05-23 06:34:36 +02:00
### チャンネルへの接続
2021-07-11 12:29:04 +02:00
チャンネルへの接続は`Stream`クラスの`useChannel`メソッドを使用します。
2021-05-16 15:23:23 +02:00
2021-05-23 06:34:36 +02:00
パラメータなし
2021-05-17 17:07:17 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
2021-05-23 06:34:36 +02:00
const mainChannel = stream.useChannel('main');
2021-05-17 17:07:17 +02:00
```
2021-05-23 06:34:36 +02:00
パラメータあり
2021-05-17 17:07:17 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
2021-05-23 06:34:36 +02:00
const messagingChannel = stream.useChannel('messaging', {
2021-05-17 17:07:17 +02:00
otherparty: 'xxxxxxxxxx',
});
```
### チャンネルから切断
2021-07-11 12:29:04 +02:00
`Channel`クラスの`dispose`メソッドを呼び出します。
2021-05-17 17:07:17 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
2021-05-23 06:34:36 +02:00
const mainChannel = stream.useChannel('main');
2021-05-17 17:07:17 +02:00
mainChannel.dispose();
```
2021-05-16 15:23:23 +02:00
### メッセージの受信
2021-07-11 12:29:04 +02:00
`Channel`クラスはEventEmitterを継承しており、メッセージがサーバーから受信されると受け取ったイベント名でペイロードをemitします。
2021-05-16 15:23:23 +02:00
2021-05-17 17:07:17 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
2021-05-23 06:34:36 +02:00
const mainChannel = stream.useChannel('main');
2021-05-17 17:07:17 +02:00
mainChannel.on('notification', notification => {
console.log('notification received', notification);
});
```
2021-05-16 15:23:23 +02:00
### メッセージの送信
2021-07-11 12:29:04 +02:00
`Channel`クラスの`send`メソッドを使用してメッセージをサーバーに送信することができます。
2021-05-16 15:23:23 +02:00
2021-05-17 17:07:17 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
2021-05-23 06:34:36 +02:00
const messagingChannel = stream.useChannel('messaging', {
2021-05-17 17:07:17 +02:00
otherparty: 'xxxxxxxxxx',
});
messagingChannel.send('read', {
id: 'xxxxxxxxxx'
});
```
2021-07-11 12:18:27 +02:00
### コネクション確立イベント
2021-07-11 12:29:04 +02:00
`Stream`クラスの`_connected_`イベントが利用可能です。
2021-07-11 12:18:27 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
stream.on('_connected_', () => {
console.log('connected');
});
```
### コネクション切断イベント
2021-07-11 12:29:04 +02:00
`Stream`クラスの`_disconnected_`イベントが利用可能です。
2021-07-11 12:18:27 +02:00
``` ts
const stream = new Misskey.Stream('https://misskey.test', { token: 'TOKEN' });
stream.on('_disconnected_', () => {
console.log('disconnected');
});
```
2021-07-11 12:29:04 +02:00
### コネクションの状態
`Stream`クラスの`state`プロパティで確認できます。
- `initializing`: 接続確立前
- `connected`: 接続完了
- `reconnecting`: 再接続中
2021-07-11 12:18:27 +02:00
2021-05-14 05:00:58 +02:00
---
2021-05-14 05:00:10 +02:00
<div align="center">
<a href="https://github.com/misskey-dev/misskey/blob/develop/CONTRIBUTING.md"><img src="./i-want-you.png" width="300"></a>
</div>