mixi2-application-sdk-ts

Étoiles10

Forks0

Mis à jour11 mai 2026 à 14:56

mixi2 Application API の非公式 TypeScript SDK (@mst-mkt/mixi2-application-sdk-ts)。認証, API クライアント, イベントハンドラ (Webhook, gRPC Stream) を提供する。 @mst-mkt/mixi2-application-sdk-ts を使って実装する場面で使用する。 mixi2 上で動作する Bot やコミュニティ Plugin の開発に利用できる。

Installation

Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.

Source

mst-mkt

mst-mkt/mixi2-application-sdk-ts

Ouvrir le dépôt GitHub Voir les dépôts du créateur

Téléchargement

Métiers associésSOC

Basé sur la classification professionnelle SOC

Développeurs de logicielsProfessions informatiques et mathématiques·SOC 15-1252

SKILL.md

readonly

name	mixi2-application-sdk-ts
description	mixi2 Application API の非公式 TypeScript SDK (@mst-mkt/mixi2-application-sdk-ts)。認証, API クライアント, イベントハンドラ (Webhook, gRPC Stream) を提供する。 @mst-mkt/mixi2-application-sdk-ts を使って実装する場面で使用する。 mixi2 上で動作する Bot やコミュニティ Plugin の開発に利用できる。

mixi2 Application SDK for TypeScript

@mst-mkt/mixi2-application-sdk-ts は mixi2 の Application API を利用するための TypeScript SDK。このスキルは SDK の利用方法の概要と各ドキュメントへの参照を提供し、SDK を使って実装する場面で使用することを想定している。

アプリケーション種別

mixi2 のアプリケーションには 2 種類ある。SDK はどちらにも同じ API クライアント/イベントハンドラで対応する。

種別	概要	受信イベント	利用 API
Bot	ユーザー向けの基本アプリケーション	リプライ, メンション, 引用, DM	基本 API
Plugin	コミュニティ管理者がインストールする拡張型 (最大 10)	Bot のイベントに加え, コミュニティ内ポスト作成, メンバー参加退出, Plugin の導入/削除	基本 API + コミュニティ操作 API

Plugin はコミュニティに要求する パーミッション と受信したい イベント を Requirement として宣言する必要がある。詳細は docs/guides/plugin.md を参照。

API クライアント

mixi2 Application API を呼び出すためのクライアント。内部では gRPC を用いて API サーバーと通信する。デフォルトの transport は @connectrpc/connect-node の createGrpcTransport が使われるが、必要に応じてカスタム transport を渡すこともできる。

import { createAuthenticator, createMixi2Client } from '@mst-mkt/mixi2-application-sdk-ts'

const authenticator = createAuthenticator({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
})
const client = createMixi2Client({ authenticator })

const { posts } = await client.getPosts({ postIdList: ['...'] })

主なメソッドは次のとおり (Bot, Plugin 共通)。

getUsers: ユーザー取得
getPosts: ポスト取得
getCommunities: 指定したコミュニティ ID の情報を取得
createPost: ポスト作成 (返信、引用、コミュニティ投稿、メディア添付に対応。テキストは 149 文字まで、メディアは最大 4 件。communityId を指定するとコミュニティへ投稿: Plugin の Community.Post.Create パーミッションが必要)
deletePost: 自身が作成したポストの削除
sendChatMessage: ダイレクトメッセージ送信 (ユーザーからの DM 受信後のみ返信可能。text または mediaId のいずれか必須)
getStamps: スタンプ一覧取得 (officialStampLanguage で公式スタンプ、communityIds で対象コミュニティのコミュニティスタンプを取得)
addStampToPost: ポストへのスタンプ付与 (対象はアプリケーションにメンションしているポストまたは Plugin がインストールされているコミュニティ内のポスト。公式スタンプは常に利用可能。コミュニティスタンプはコミュニティポストにのみ付与可能で Community.Post.Stamp.Create パーミッションが必要)
initiatePostMediaUpload: メディアアップロード開始
getPostMediaStatus: メディアアップロード状態取得

Plugin 固有のメソッド (docs/guides/plugin.md を参照)。

getCommunitiesUsingApplication: Plugin がインストールされているコミュニティと各コミュニティが使用中のアプリケーションバージョン一覧を取得 (ページングは nextCursor → cursor)
getCommunityTimeline: コミュニティのタイムライン (ポスト一覧) を取得 (Community.Post.Read。untilCursor / sinceCursor でページング)
getCommunityMemberList: コミュニティのメンバー一覧を取得 (Community.MemberList.Read。ページングは nextPaginationCursor → paginationCursor)
restrictCommunityPost: コミュニティのポストをタイムラインから非表示にする (ポストは削除されない。Community.Post.Restrict)
sendDirectMessageToCommunityMember: コミュニティメンバーへ DM 送信 (Community.Member.DirectMessage.Create。text または mediaIds のいずれか必須)

引数や返り値などの詳細は docs/guides/client.md および docs/guides/plugin.md に記載されている。

認証トークンは authenticator が自動取得しキャッシュする。(有効期限の 60 秒前に再取得)

レート制限は全 RPC 共通で 1 分あたり 20 回 (initiatePostMediaUpload のみ 1 時間あたり 200 回も追加で適用)。メディアアップロード総量は 1 GB / 日。subscribeEvents (gRPC ストリーム) には回数制限なし。

イベントを受ける

Webhook と gRPC Stream の 2 方式がある。イベントは順序保証なし、Best-effort 配信。

条件	Webhook	gRPC Stream
用途	HTTPS に対応したサーバー環境	ローカル開発やプロトタイピング
公開 HTTPS エンドポイント	必要	不要
常駐プロセス	不要	必要
配信失敗時	最大 3 回リトライ (重複可能性)	切断中のイベントは失われる
認証	SDK が Ed25519 署名を検証	SDK がアクセストークンを付与

イベントハンドラ (Webhook, gRPC Stream 共通)

import { createEventHandler, EventReason } from '@mst-mkt/mixi2-application-sdk-ts'

const eventHandler = createEventHandler({
  postCreated: async (event) => {
    // event.post, event.issuer, event.postedCommunity, event.eventReasonList: EventReason[]
    if (event.eventReasonList.includes(EventReason.POST_REPLY)) {
      /* ... */
    }
  },
  chatMessageReceived: async (event) => {
    // event.message, event.issuer, event.eventReasonList
  },
  communityMemberChanged: async (event) => {
    // event.community, event.member, event.eventReasonList (Plugin のみ)
  },
  communityPluginManaged: async (event) => {
    // event.community, event.eventReasonList (Plugin のみ)
  },
})

`EventType`	`eventReasonList` の値	ハンドラ	対象
`POST_CREATED`	`POST_REPLY`, `POST_MENTIONED`, `POST_QUOTED`, `POST_COMMUNITY`	`postCreated`	Bot/Plugin
`CHAT_MESSAGE_RECEIVED`	`DIRECT_MESSAGE_RECEIVED`	`chatMessageReceived`	Bot/Plugin
`COMMUNITY_MEMBER_CHANGED`	`COMMUNITY_MEMBER_JOINED`, `COMMUNITY_MEMBER_LEFT`	`communityMemberChanged`	Plugin
`COMMUNITY_PLUGIN_MANAGED`	`COMMUNITY_PLUGIN_INSTALLED`, `COMMUNITY_PLUGIN_UNINSTALLED`	`communityPluginManaged`	Plugin

各ハンドラは省略可能。第 2 引数で生の Event も受け取れる
eventReasonList は配列で、複数理由が同時に立ちうる
PING イベントは SDK が自動スキップするためハンドラには届かない
ハンドラ内のエラーは onError (デフォルト console.error) に委譲され、他イベントの処理には影響しない
POST_COMMUNITY は Plugin のみ。postCreated ハンドラの event.postedCommunity (任意) に投稿先コミュニティが含まれる
communityMemberChanged は Requirement に Community.Member.Joined を宣言した Plugin のみが受信する
communityPluginManaged は Requirement への宣言なしに、すべての Plugin に自動配信される (初期処理やクリーンアップに利用)

Webhook で受信する

import { createWebhookHandler } from '@mst-mkt/mixi2-application-sdk-ts'

const webhookHandler = createWebhookHandler(
  {
    signaturePublicKey: process.env.SIGNATURE_PUBLIC_KEY!,
    syncHandling: true, // サーバーレスでは必須
  },
  eventHandler,
)

webhookHandler は Web 標準 Request, Response を受ける任意のプラットフォームやフレームワークで使える

// 例: Vercel
export const POST = (req: Request) => webhookHandler(req)

// 例: Hono
import { Hono } from 'hono'

const app = new Hono()
app.mount('/events', webhookHandler)

export default app

signaturePublicKey は mixi2 Developer Platform で発行された公開鍵を指定する
mixi2 側のタイムアウトは 3 秒。失敗時は 30 秒間隔で最大 3 回リトライされる
リトライで同じイベントが重複して届きうるため、アプリケーション側で冪等性を確保する
サーバーレス環境 (Vercel, Deno Deploy, Cloudflare Workers など) では syncHandling: true が必須
- 省略するとレスポンス後にプロセスが終了しハンドラが中断する
- 同期モードでは 3 秒以内に処理を完了する必要がある
POST 以外のリクエストには 405 を返す

gRPC Stream で受信する

import { createStreamWatcher } from '@mst-mkt/mixi2-application-sdk-ts'

const watcher = createStreamWatcher({ authenticator }, eventHandler)

const controller = new AbortController()
await watcher.watch(controller.signal)

接続エラー時は指数バックオフ (1s -> 2s -> 4s) で最大 3 回再接続する。接続成功でカウンターはリセット
maxRetries (デフォルト 3) を超えたら元のエラーが throw される
再接続中に発生したイベントは失われる。厳密な到達保証が必要なら Webhook を使う

メディア付き投稿

4 段階で実行する。詳細は docs/guides/client.md の「メディアのアップロード」を参照。

client.initiatePostMediaUpload({ mediaType, contentType, dataSize }) で uploadUrl と mediaId を取得する
uploadUrl に SDK の外で POST でバイナリをアップロードする。Content-Type と Authorization: Bearer <accessToken> ヘッダが必要
client.getPostMediaStatus({ mediaId }) の status が 3 (STATUS_COMPLETED) になるまでポーリングする
client.createPost({ text, mediaIdList: [mediaId] }) でポストに添付する (最大 4 件)

制約: 最大サイズは画像 15 MB, 動画 50 MB。アップロード有効期限は画像 200 秒, 動画 600 秒。

import { MediaType } from '@mst-mkt/mixi2-application-sdk-ts'

const { mediaId, uploadUrl } = await client.initiatePostMediaUpload({
  mediaType: MediaType.IMAGE, // or MediaType.VIDEO
  contentType: 'image/jpeg',
  dataSize: BigInt(imageData.byteLength),
})

const accessToken = await authenticator.getAccessToken()

await fetch(uploadUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'image/jpeg',
    Authorization: `Bearer ${accessToken}`,
  },
  body: imageData,
})

Plugin の Requirement

Plugin がコミュニティに対して要求するパーミッションと受信したいイベントのセット。mixi2 Developer Platform の「Requirement」設定画面で宣言する。SDK 側の設定ではない。

パーミッションと対応 API:

パーミッション	対応 API
`Community.Post.Read`	`getCommunityTimeline`
`Community.Post.Create`	`createPost` (`communityId` 指定時)
`Community.Post.Restrict`	`restrictCommunityPost`
`Community.MemberList.Read`	`getCommunityMemberList`
`Community.Post.Stamp.Create`	`addStampToPost` (コミュニティポスト対象)
`Community.Member.DirectMessage.Create`	`sendDirectMessageToCommunityMember`

宣言する Requirement イベント:

イベント名 (Developer Platform)	SDK ハンドラ	備考
`Reaction.Post.Replied`	`postCreated` (`POST_REPLY`)	Bot/Plugin
`Reaction.Post.Mentioned`	`postCreated` (`POST_MENTIONED`)	Bot/Plugin
`Reaction.DirectMessage.Received`	`chatMessageReceived` (`DIRECT_MESSAGE_RECEIVED`)	Bot/Plugin
`Community.Post.Created`	`postCreated` (`POST_COMMUNITY`)	Plugin のみ
`Community.Member.Joined`	`communityMemberChanged`	Plugin のみ。退出も同イベントで通知

Requirement を保存するたびに新しいバージョンが作成される。既にインストール済みのコミュニティは管理者がアップデートするまで古いバージョンで動作するため、変更時は後方互換性を維持する。インストール済みのコミュニティと利用バージョンは getCommunitiesUsingApplication で確認できる。

詳細情報

利用者ガイド
- 参照
  - npm package: node_modules/@mst-mkt/mixi2-application-sdk-ts/docs/
  - GitHub: https://github.com/mst-mkt/mixi2-application-sdk-ts/blob/main/docs/
- 構成
  - getting-started.md
  - guides/
    - guides/client.md
    - guides/plugin.md
    - guides/events.md
    - guides/events-webhook.md
    - guides/events-stream.md
  - deployments/
    - deployments/vercel.md
    - deployments/deno-deploy.md
    - deployments/cloudflare-workers.md
実装サンプル: https://github.com/mst-mkt/mixi2-application-sdk-ts/tree/main/example
mixi2 Developer Platform 公式ドキュメント: https://developer.mixi.social/docs/llms-full.txt
Protobuf 定義: https://github.com/mixigroup/mixi2-api
公式 SDK (Go): https://github.com/mixigroup/mixi2-application-sdk-go

name	mixi2-application-sdk-ts
description	mixi2 Application API の非公式 TypeScript SDK (@mst-mkt/mixi2-application-sdk-ts)。認証, API クライアント, イベントハンドラ (Webhook, gRPC Stream) を提供する。 @mst-mkt/mixi2-application-sdk-ts を使って実装する場面で使用する。 mixi2 上で動作する Bot やコミュニティ Plugin の開発に利用できる。