はじめに

前提条件

• Node.js 20.19.0 以上
• mixi2 Developer Platform で開発者登録が完了していること
• アプリケーションを作成し、認証情報（Client ID / Client Secret / Token URL 等）を取得済みであること

対応環境

mixi2-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 互換レイヤーで動かします
• 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 にはクライアント機能がないためです

Node.js 20 では、createWebhookHandler が使う Web Crypto の Ed25519 が ExperimentalWarning を出します。Node.js では WebhookServer の利用をおすすめします。

ヒント

サーバーレス環境ではランタイムが対応していても gRPC ストリーミングを常時接続できない場合があります。環境に合わせて Webhook と gRPC ストリーミング を使い分けてください。

インストール

Node.js バージョンについて

mixi2-js v1.5.0 より、Node.js v20.19.0 未満はサポートされなくなりました。 Node.js v18 系では動作しません。Node.js v20.19.0 以上をご使用ください。

npm

npm install mixi2-js

JSR

npx jsr add @otoneko1102/mixi2-js

ESM・CommonJS の両方に対応しています。TypeScript の型定義 (.d.ts) も同梱されています。

ノート

JSR 経由でインストールした場合、インポートパスは 'mixi2-js' ではなく '@otoneko1102/mixi2-js' になります。 以降のコード例はすべて npm 版のパスで記載しています。JSR 版をお使いの場合は適宜読み替えてください。

AI エージェント向けの Skill

AI エージェント (Claude Code、Codex など) が mixi2-js を使ったコードを書くための Skill を公開しています。SDK の使い方の要点、イベントの種類、ヘルパーの一覧、各ドキュメントへのリンクがまとまっています。

GitHub CLI

gh skill install otnc/mixi2-js

npx skills

npx skills add otnc/mixi2-js

Skill の本体は skills/mixi2-js/SKILL.md です。

モジュール一覧

モジュール	説明
OAuth2Authenticator	OAuth2 Client Credentials 認証（トークン自動キャッシュ・有効期限 1 分前に自動更新）
Client	gRPC API クライアント (公式 API の全 15 RPC に対応)
WebhookServer	HTTP Webhook サーバー（Ed25519 署名検証・Ping 自動応答）
StreamWatcher	gRPC ストリーミング（指数バックオフによる自動再接続）

認証

すべての API 操作に OAuth2 認証が必要です。

npm

// ESM
import { OAuth2Authenticator } from 'mixi2-js';
// CJS
const { OAuth2Authenticator } = require('mixi2-js');

JSR

import { OAuth2Authenticator } from '@otoneko1102/mixi2-js';

const authenticator = new OAuth2Authenticator({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  tokenUrl: process.env.TOKEN_URL!,
});

// アクセストークンを取得（キャッシュ済みの場合は即座に返却）
const token = await authenticator.getAccessToken();

OAuth2Authenticator

OAuth2 Client Credentials フローによる認証を管理します。

new OAuth2Authenticator(options: AuthenticatorOptions)

プロパティ	型	説明
clientId	string	OAuth2 クライアント ID
clientSecret	string	OAuth2 クライアントシークレット
tokenUrl	string	トークンエンドポイント URL

メソッド	戻り値	説明
getAccessToken()	Promise<string>	アクセストークンを取得。有効期限の 1 分前までキャッシュし、自動更新する

Authenticator インターフェースを実装しているため、カスタム認証を独自に実装することも可能です。

ヒント

認証情報は環境変数またはシークレット管理システムから読み込んでください。ソースコードへのハードコードは避けてください。

詳細は 公式ドキュメント を参照してください。