JavaScript SDK

JavaScript SDK、@owncast/plugin-sdk は、Owncast プラグインを記述する最も一般的な方法です。 JavaScript または TypeScript を書き、CLI がそれらを単一のインストール可能なプラグインにバンドルし、Owncast サーバー内でサンドボックス実行します。 If you're choosing an authoring path, see the plugins overview.

JavaScript plugins require Owncast v0.3.0

プラグイン SDK は Owncast 0.3.0 で新しく導入されたもので、API はまだ進化中です。 バグが見つかったり提案がある場合は、issue を開いてください または コミュニティとライブチャット してください。

このページは JavaScript 固有のレイヤーです: スキャフォールディング、definePlugin、CLI、そして TypeScript。 ハンドラ、API、権限、マニフェストは両 SDK で同じ動作をし、それぞれ参照ページがあります。

リファレンス文書への対応

共有リファレンスは API を正規形（JavaScript 形）で記載しているので、そのまま読めます。 簡単な案内:

リファレンスでは	JavaScript では
ハンドラを定義する	a method on definePlugin({ ... })
イベントのハンドラ（例: chat.message.received）	onChatMessage(msg): キャメルケースで、on + イベント名
ホスト API を呼ぶ（例: owncast.chat.sendAction）	同一: owncast.chat.sendAction(text)
ペイロードフィールド	キャメルケース: msg.user.displayName, msg.clientId
フィルタ結果	filter.pass() / filter.modify(payload) / filter.drop(reason)
Declare a plugin-owned custom hook	on: { "my.event"(payload) { … } }. Owned as <your-slug>.my.event
プラグインをビルド / テストする	npm run package / npm test

前提条件

• 管理できる Owncast サーバー（バージョン 0.3.0 以降）。
• Node.js 18 以降（確認: node --version）。

新しいプラグインをスキャフォールドする

SDK を手動でインストールする必要はありません。 create-owncast-plugin でプロジェクトをスキャフォールドすると、生成される package.json に @owncast/plugin-sdk が依存関係として既に記載されています:

npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install     # fetches the test and serve helpers

引数に希望のスラッグを渡してください。 スキャフォールドはディレクトリ名、出力ファイル名、URL プレフィックスにそれを使用します。 スラッグは小文字の英字、数字、ハイフンで、先頭は英字です。

これで次のものができます:

my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test

npm install は node_modules/ も作成します。 これらは自動作成されませんが、icon.png（管理画面のプラグイン一覧に表示）、public/ ディレクトリ（静的ファイルは /plugins/my-plugin/ で提供）、および assets/ ディレクトリ（マニフェストフィールドにホストがインラインするファイル）を追加できます。

npm install は postinstall ステップを実行して、事前ビルド済みのテストおよびサーブ用ホストバイナリ（シナリオランナーと開発サーバー）を取得します。 プラグインのビルドとパッケージングにはダウンロードは不要です。 この postinstall が唯一のネットワークステップで、それ以降はすべてローカルです。

プラグインを書く

プラグインは definePlugin に渡すオブジェクトです。 反応させたいイベントごとにメソッドを定義してください: SDK はどのメソッドが存在するかからマニフェストの購読リストを導出するため、別途リストを同期させる必要はありません。

const { definePlugin, owncast, filter } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },

  filterChatMessage(msg) {
    return msg.body.includes('spam') ? filter.drop('spam') : filter.pass();
  },
});

The package exports four things you'll use:

• definePlugin(handlers): ハンドラを登録し、エクスポートするプラグインオブジェクトを返します。
• owncast: ホスト API 名前空間（owncast.chat.send(...), owncast.kv.get(...) など）。 メソッド名は camelCase です。 各呼び出しはマニフェストで宣言した対応する権限によって制御されます。 APIs reference を参照してください。
• filter: フィルタ結果のコンストラクタ: filter.pass(), filter.modify(payload), filter.drop(reason)。 filterChatMessage からのみ使用されます。
• authCheck: verdict helpers for the onAuthCheck handler of an auth.gate plugin: authCheck.ok(), authCheck.refresh({ ttl? }), authCheck.deny(reason?).

ハンドラ名はキャメルケースで、handlers reference に記載のランタイムイベントにマップします: onChatMessage, filterChatMessage, onChatUserJoined, onStreamStarted, onTick, onFediverseFollow, onHttpRequest など。 ペイロードフィールドもキャメルケースです（msg.user.displayName, msg.clientId）。

Beyond top-level methods, custom-event handlers are passed as a nested object keyed by event type: on: { "my.event"(payload) {} }. Dynamic viewer pages use plain functions. onTabContent(ctx) receives the requested manifest.tabs object key as ctx.slug. onPageContent(ctx) receives manifest.extraPageContent.slug. キーを取らないものが二つあります: onPageStyles() と onPageScripts() はリクエスト時にビューアページへ挿入される CSS と JavaScript を返し、ui.modify によって制御されます。 Rather than hand-rolling prefix parsing in onChatMessage, you can declare a commands table that the host's built-in !help picks up automatically. これらは JavaScript 用のサブジェクトページで示されています: Handlers, Commands, UI。

TypeScript

パッケージには index.d.ts が同梱されているため、追加設定なしで全てのイベントペイロードとホスト API に対するオートコンプリートと型チェックが受けられます。 エントリを src/plugin.ts と名付けると、CLI は同じ方法でコンパイルします:

import { definePlugin, owncast, filter, ChatMessage } from '@owncast/plugin-sdk';

export default definePlugin({
  onChatMessage(msg: ChatMessage) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});

ビルドは順に src/plugin.ts, src/plugin.js, plugin.ts, plugin.js を検出します。 型は宣言のみです: 別途のコンパイルステップや tsconfig は不要です。

CLI

SDK は owncast-plugin CLI をインストールし、スキャフォールドが書き込む package.json のスクリプト経由で公開されます:

コマンド	スクリプト	動作内容
owncast-plugin build	npm run build	src/plugin.{js,ts} を中間ビルド成果物にバンドルする
owncast-plugin test	npm test	ビルドしてから実際のランタイムで __tests__/ のシナリオを実行する
owncast-plugin serve	npm run serve	ローカル開発サーバー: http://localhost:8080/plugins/<slug>/
owncast-plugin package	npm run package	すべてをビルドしてバンドルし、配布する <slug>.ocpkg を作成します: これが配布するファイルです

npm run package   # produces my-plugin.ocpkg
npm test          # runs your scenarios
npm run serve     # iterate against a local dev server

npm run package only rebuilds when the bundle is missing. After changing source, run npm run build first so the package doesn't ship stale code.

.ocpkg は単一の配布成果物です: マニフェスト、バンドル済みコード、public/ と assets/ ディレクトリ、オプションの icon.png と INSTRUCTIONS.md を含みます。 中身とインストール方法については Packaging & distribution を参照してください。

JavaScript では、npm test は __tests__/*.test.js ファイル（ループ、ヘルパー、フィクスチャで配列を構築して runScenarios を呼ぶ）か、静的な __tests__/*.test.json ファイルを実行します。 完全なシナリオデータモデルとローカル開発サーバー（npm run serve）は Testing ページにあります。

知っておくべき制約

CLI はコードをサーバーのサンドボックス内で実行される単一ファイルにバンドルします。Node 上では動作しません。 そのサンドボックスはプラグインの書き方に影響します:

• アウトバウンド HTTP にはグローバルの fetch、axios、または Node の http をラップするパッケージではなく owncast.http.fetch を使用してください。 ネットワークアクセスはホスト API 経由で行われ、network.fetch 権限で制御されます。 APIs reference を参照してください。
• すべての npm パッケージが動くわけではありません。 ピュアな JavaScript パッケージは問題なくバンドルできます。 Node.js ランタイムを必要とするものは動作しません。 Third-party libraries を参照してください。

サードパーティライブラリ

Owncat cautions you依存関係を追加する前にこれを読んでください

npm パッケージは ピュアな JavaScript の場合にのみ動作します。 プラグインはサンドボックスで動き、Node ではないため、fs, net, http/https, path, crypto, process, child_process に触れるパッケージは綺麗にバンドルされてもそのコードが実行されると例外を投げます。

パッケージはあなたが使わないパスで Node の組み込みを参照することもあるので、使う部分をテストしてください。 アウトバウンド HTTP には HTTP クライアントパッケージではなく owncast.http.fetch を使用してください。

page-content-demo の例は mustache パッケージをこのように使用しています。

パッケージに含まれるもの

• index.js: definePlugin, コマンドハンドラ, owncast.* ホストラッパー, およびフィルタヘルパーを含むランタイム。
• index.d.ts: 全てのイベントペイロードとホスト API の TypeScript 宣言。
• testing.js: runScenarios / runScenarioFiles テスト API。
• bin/owncast-plugin: CLI（build, test, serve, package）。
• scripts/postinstall.js: インストール時に事前ビルド済みのテストおよびサーブホストバイナリを取得するスクリプトで、npm test と npm run serve で使用されます。

次に進む場所

• Handlers reference: 購読できるすべてのイベントとそのペイロード形状。
• APIs reference: すべての owncast.* メソッドとそれに必要な権限。
• Testing: 完全なシナリオデータモデル。
• Packaging & distribution: .ocpkg の構築とインストール。
• Example plugins: 機能ごとに一つずつ、コピーして始められる完全なスターターポイント。
• SDK source: @owncast/plugin-sdk パッケージとツールチェイン。