@mst-mkt/mixi2-application-sdk-ts
v1.0.0
Published
mixi2 Application SDK for TypeScript (Unofficial)
Readme
mixi2 Application SDK for TypeScript
mixi2 の Application API を利用するための TypeScript SDK です。
[!NOTE] この SDK は mixi 公式ではありません。 以下の公式リソースをもとに開発しています。
インストール
npm
pnpm add @mst-mkt/mixi2-application-sdk-tsJSR
deno add jsr:@mst-mkt/mixi2-application-sdk-tsSkills
このライブラリを使用するための Skill を公開しています。以下のような方法でインストールできます。
GitHub CLI (gh skill)
gh skill install mst-mkt/mixi2-application-sdk-tsvercel-labs/skills (npx skills)
npx skills add mst-mkt/mixi2-application-sdk-ts環境サポート
このライブラリは以下のランタイム API に依存しており、環境によって利用できる機能が異なります。
node:http2: gRPC ストリーミングに使用crypto.subtle: Webhook の署名検証に使用
| 環境 | auth | client | event/webhook | event/stream |
| ------------------ | ------ | -------- | --------------- | -------------- |
| Node.js | ✅ | ✅ | ✅ | ✅ |
| Deno | ✅ | ✅ | ✅ | ✅ |
| Bun | ✅ | ✅ | ✅ | ✅ |
| Cloudflare Workers | ✅ | ⚠️ | ✅ | ❌ |
- Node.js: 18.4.0 以降 (recommended: 22 以降)
crypto.subtle: 18.4.0 以降 (ref: https://nodejs.org/en/blog/release/v18.4.0#notable-changes)node:http2: 10.10.0 以降 (ref: https://nodejs.org/en/blog/release/v10.10.0#notable-changes)- v20 は既に EOL のため、
engines.nodeは v22 以降を指定している。
- Deno: 1.26.0 以降
crypto.subtle: 1.26.0 以降 (ref: https://deno.com/blog/v1.26#webcrypto-secure-curves)node:http2: 1.37.0 以降 (ref: https://deno.com/blog/v1.37#nodejs-compatibility-improvements)
- Bun: 0.5.7 以降
crypto.subtle: 0.5.7 以降 (ref: https://bun.sh/blog/bun-v0.5.7#changelog)node:http2: 1.0.13 以降 (ref: https://bun.sh/blog/bun-v1.0.13#http2-client-support)
- Cloudflare Workers: 実験的対応
crypto.subtle: 2023-04-28 以降 (ref: https://developers.cloudflare.com/workers/platform/changelog/#2023-04-28)node:http2: 非対応 (ref: https://developers.cloudflare.com/workers/runtime-apis/nodejs/#supported-nodejs-apis)node:http2を回避して利用する方法がある (ref: docs/deployments/cloudflare-workers)
[!TIP] サーバーレス環境ではランタイムが対応していても gRPC ストリーミングが利用できない場合があります。環境に応じて Webhook と gRPC ストリーミングを使い分けてください。
使い方
詳細な使い方については ドキュメント を参照してください。
API クライアント
createAuthenticator で認証情報を設定し、createMixi2Client で API クライアントを作成します。
import { createAuthenticator, createMixi2Client } from '@mst-mkt/mixi2-application-sdk-ts'
const authenticator = createAuthenticator({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
})
const client = createMixi2Client({ authenticator })
const { posts } = await client.getPosts({ postIdList: ['5efb4595-fe2d-4c52-b078-b85020385955'] })API クライアントの詳細 >
Plugin 固有の API の詳細 >
イベント処理
mixi2 からのイベント (投稿作成, チャット受信, コミュニティ関連) を処理するハンドラーを定義します。Webhook と gRPC ストリーミングの両方で共通のハンドラーを利用できます。
import { createEventHandler } from '@mst-mkt/mixi2-application-sdk-ts'
const eventHandler = createEventHandler({
chatMessageReceived: async ({ message }) => {
// チャット受信時の処理
},
postCreated: async ({ post }) => {
// 投稿 (引用, メンション, リプライ, コミュニティへの投稿) 作成時の処理
},
communityMemberChanged: async ({ community, member }) => {
// コミュニティのメンバー参加・退出時の処理 (Plugin のみ)
},
communityPluginManaged: async ({ community }) => {
// Plugin のコミュニティへの導入・削除時の処理 (Plugin のみ)
},
})Webhook
イベントハンドラーと署名検証用の公開鍵から Webhook ハンドラーを作成します。返り値は (req: Request) => Promise<Response> 型の関数で、Web 標準の Request / Response を使う任意の環境で動作します。
import { createWebhookHandler } from '@mst-mkt/mixi2-application-sdk-ts'
const webhookHandler = createWebhookHandler(
{ signaturePublicKey: SIGNATURE_PUBLIC_KEY },
eventHandler,
)gRPC Stream
イベントハンドラーと認証情報から gRPC ストリーミングのウォッチャーを作成します。watch() は AbortSignal を渡すことで、任意のタイミングで監視を停止できます。
import { createStreamWatcher } from '@mst-mkt/mixi2-application-sdk-ts'
const streamWatcher = createStreamWatcher({ authenticator }, eventHandler)
await streamWatcher.watch()デプロイ
- Deno Deploy
- Vercel
- Cloudflare Workers
開発
CONTRIBUTING.md を参照してください。
Used by
- ドキュメント更新検知 BOT @mixi2_docs (repo)
- 334 Ranker @334_ranker
- 怪レい日本语 @correctjp