Roomy

教室アナウンス API w/ Discord 🥂 for @iputapp

Tech Stack

Environments	Languages	Linters	Frameworks	Libraries	Testing	CI/CD	PaaS

Other

• discord-interactions-js
• discord-api-types
• googleapis
• tsx

Development

1. 必須
2. 環境変数
3. コマンド

必須

node = ">=22"
pnpm = ">=10"

Tip

詳細は.prototoolsおよびpackage.jsonのengines|packageManagerを参照する。

環境変数

NODE_ENV=development
API_ENDPOINT_URL=https://your_api_endpoint_url
API_ENDPOINT_SECRET=your_generated_secret
DISCORD_TOKEN=your_discord_token
DISCORD_APPLICATION_ID=your_discord_application_id
DISCORD_PUBLIC_KEY=your_discord_public_key
DISCORD_CHANNEL_ID=your_channel_id
GOOGLE_CLIENT_EMAIL=your_google_client_email
GOOGLE_PRIVATE_KEY=your_google_private_key
SPREADSHEET_ID=your_spreadsheet_id

Tip

詳細は.env.exampleを参照する。

コマンド

パッケージのインストール

pnpm i

Important

初回インストールの後（保存時のフォーマットが動作しない場合）は、VS Code (IDE)を再起動する。

開発サーバの起動

pnpm dev

開発サーバをパブリックに公開

pnpm dev
pnpm start

ngrokを使用してlocalhost:8787をパブリックに公開する。

Important

ngrok - Setup & Installationから環境に合わせてngrokを導入する。

Windows はDownload for Windows (64-Bit)でダウンロードおよび解凍した exe ファイルを、レポジトリのルートディレクトリに置く。

Tip

テスト用 Discord App INTERACTIONS ENDPOINT URLの設定に利用する。

ドキュメント: Discord Developers - Set up a public endpoint

リンターのチェック

pnpm lint

コードのフォーマット

pnpm format

デプロイ

pnpm deploy:mini

コマンドを Discord に登録

pnpm register

Tip

スラッシュコマンドの一覧はsrc/constants/discord.tsのDISCORD_COMMANDSを参照する。

API エンドポイント認証のキーを生成

pnpm gen:secret

Important

生成したキーは環境変数 API_ENDPOINT_SECRET に設定する。

Documents

• API エンドポイント
• 実行スケジュールを変更する

API エンドポイント

• API v1

API v1

• Discord v1
• Google v1
• Cron v1

Discord v1

POST /v1/discord/interaction

Discord App INTERACTIONS ENDPOINT URLの設定に利用する。

Google v1

GET /v1/google/sheets/room

Google Sheets から教室情報を取得する。

クエリパラメータ	値	必須
period	today または week	❌

例: 今週の教室 /v1/google/sheets/room?period=week

Tip

periodは省略できる。デフォルトはperiod=todayになる。

Cron v1

POST /v1/cron

定期アナウンスの Cron に設定する。

認証について

センシティブな API エンドポイントは認証を設けている。

認証付きのパスは以下:

• Google v1
• Cron v1

クライアントでのリクエスト例

async function makeAuthenticatedRequest(path: string) {
  const timestamp = Date.now().toString();
  const apiKey = "your_secure_random_string"; // API_ENDPOINT_SECRETと同じ値

  // 署名の生成
  const payload = timestamp + path;
  const signature = await generateHMAC(payload, apiKey);

  const response = await fetch(`https://your-api.com${path}`, {
    headers: {
      "X-Request-Timestamp": timestamp,
      "X-Signature": signature,
    },
  });

  return response;
}

Note

generateHMAC()の内容はsrc/utils/crypto.tsを参照する。

実行スケジュールを変更する

wrangler.tomlのcronsを変更する。

Tip

cron のタイムゾーンはUTCのため、日本時間(JST)-9時間を設定する。