mixi2 の Application API を利用するための 非公式 TypeScript/JavaScript SDK です。
公式 Go SDK および 公式 API 仕様 に基づいて作成されています。
Note
これは MIXI 社公式のプロダクトではありません。コミュニティメンバーによるオープンソースプロジェクトです。
Warning
mixi2-js v1.5.0 より、Node.js v20.19.0 未満はサポートされなくなりました。 Node.js v18 系では動作しません。Node.js v20.19.0 以上をご使用ください。
npm install mixi2-js
# or
npx jsr add @otoneko1102/mixi2-jsESM・CommonJS の両方に対応しています。TypeScript の型定義 (.d.ts) も同梱されています。
AI エージェント (Claude Code、Codex など) が mixi2-js を使ったコードを書くための Skill を公開しています。次のどちらかの方法でインストールできます。
gh skill install otnc/mixi2-jsnpx skills add otnc/mixi2-jsmixi2-js は以下のランタイム API に依存しているため、環境によって使える機能が異なります。
node:http2(@grpc/grpc-js経由): API クライアントと gRPC ストリーミングnode:httpとnode:crypto(Ed25519):WebhookServerのサーバーと署名検証- Fetch API (
Request/Response) とcrypto.subtle(Ed25519):createWebhookHandlerの受信と署名検証 fetchとbtoa: 認証とメディアアップロード
| 環境 | 認証 (OAuth2Authenticator) |
API クライアント (Client) |
Webhook (WebhookServer) |
Webhook (createWebhookHandler) |
gRPC ストリーミング (StreamWatcher) |
|---|---|---|---|---|---|
| Node.js | ✅ | ✅ | ✅ | ✅ | ✅ |
| Bun | ✅ | ✅ | ✅ | ✅ | ✅ |
| Deno | ✅ | ✅ | ✅ | ✅ | ✅ |
| Cloudflare Workers | ✅ | ❌ | ✅ | ✅ | ❌ |
✅ 動作確認済み、
詳細な対応状況
CI でビルド済みのパッケージを各ランタイムで動かし、結果を毎回確認しています。Node.js / Bun / Deno では、ローカルの TLS gRPC サーバーに対する実際の通信 (API 呼び出しとストリームでのイベント受信)、Webhook の署名検証、認証を確認しています。Cloudflare Workers は Wrangler 経由で workerd 上で動かしています。
- Node.js: 20.19.0 以降。テストは 20.19.0 / 22 / 24 で実行しています
- Bun: 最新版で確認しています (1.4 系で確認済み)
- Deno: 2.x の最新版で確認しています (2.9 系で確認済み)。
npm:mixi2-jsまたは JSR 版を Node.js 互換レイヤーで動かします - Node.js 20 では、
createWebhookHandlerが使う Web Crypto の Ed25519 がExperimentalWarningを出します。Node.js ではWebhookServerの利用をおすすめします - Cloudflare Workers:
nodejs_compatを有効にすると、認証と Webhook が使えます。WebhookServerはcloudflare:nodeのhttpServerHandlerで Workers のfetchにつなぎます (使い方はドキュメントを参照)。API クライアントと gRPC ストリーミングは使えません。mixi2 の API は HTTP/2 の gRPC だけを受け付けますが、Workers のfetchは外部へ HTTP/1.1 で接続し、node:http2にはクライアント機能がないためです
Tip
サーバーレス環境ではランタイムが対応していても gRPC ストリーミングを常時接続できない場合があります。環境に合わせて Webhook と gRPC ストリーミングを使い分けてください。対応環境を広げる取り組みは Issues で管理しています。
| モジュール | 説明 |
|---|---|
OAuth2Authenticator |
OAuth2 Client Credentials 認証（アクセストークンの取得・キャッシュ・有効期限 1 分前に自動更新） |
Client |
gRPC API クライアント (公式 API の全 15 RPC に対応) |
WebhookServer |
HTTP Webhook サーバー（Ed25519 署名検証・Ping 自動応答） |
createWebhookHandler |
Fetch API (Request → Response) で動く Webhook ハンドラ (Cloudflare Workers・Deno・Bun・Hono など) |
StreamWatcher |
gRPC ストリーミング（指数バックオフによる自動再接続） |
mixi2-js/helpers は、公式 API 仕様には含まれない SDK 独自の便利ユーティリティを提供します。
| ヘルパー | 説明 |
|---|---|
EventRouter |
イベントタイプ別にハンドラを登録できるルーター |
PostBuilder |
メソッドチェーンでポスト作成リクエストを組み立てるビルダー |
MediaUploader |
メディアアップロードの開始〜完了待機を自動化 |
ReasonFilter |
EventReason ベースでイベントをフィルタリング |
EventDeduplicator |
Webhook リトライ等による重複イベントをスキップ |
EventLogger |
受信イベントをログ出力するデバッグ用ミドルウェア |
TextSplitter |
長いテキストを 149 文字制限内に自動分割 |
Address |
公式エンドポイント URL を返すヘルパー |
CommunityFilter |
特定のコミュニティのイベントだけを通す (Plugin 向け) |
MemberEventRouter |
メンバーの参加・退出イベントを振り分け (Plugin 向け) |
PluginManagedRouter |
インストール・アンインストールイベントを振り分け (Plugin 向け) |
MemberListPager |
コミュニティのメンバー一覧をページ送りで取得 (Plugin 向け) |
ApplicationPager |
インストール済みコミュニティ一覧をページ送りで取得 (Plugin 向け) |
使い方・API リファレンス・拡張機能の詳細は ドキュメントサイト を参照してください。
- mixi2-js ドキュメント
- mixi2 Developer Platform 公式ドキュメント
- mixi2-api — API 定義（Protocol Buffers）
- mixi2-application-sdk-go — 公式 Go SDK
- mixi2-application-sample-go — サンプルアプリケーション
- 公式ドキュメントの GitHub リポジトリ一覧 — mixi2-js もコミュニティによるリポジトリとして掲載されています
mixi2-js のメジャーバージョンは、対応する mixi2 API のメジャーバージョンに合わせています (mixi2 API v1.x には mixi2-js v1.x が対応)。SDK 独自の破壊的変更はマイナーバージョンで行い、CHANGELOG の Breaking changes に記載します。詳細は CONTRIBUTING.md を参照してください。
貢献を歓迎しています！詳細は CONTRIBUTING.md を参照してください。
このプロジェクトは Contributor Covenant 行動規範 に準拠しています。
proto/ 以下の Protocol Buffers 定義は mixi2-api (Copyright 2025 MIXI, Inc.、Apache-2.0) から同梱しています。サードパーティのライセンス表記は THIRD_PARTY_NOTICES.md を参照してください。