macOSの通知をntfyへ転送する方法

まず確認：どちら方向の通知が必要ですか？

「ntfy macOS」で検索されるケースには、向きが正反対の2つの用途があります：

• ntfyトピックの通知をMacで受け取る（受信）： ブラウザで ntfy.sh/app を開いてWeb通知を許可するか、CLIクライアントの ntfy subscribe を使います。この用途にはNotiFerryは必要ありません。
• Mac上のアプリの通知をntfyトピックへ送る（送信）： ntfy自体はmacOSの通知センターを読み取る機能を持っていません。自分で書けるスクリプトなら curl 1行で送れますが、スクリプト化できないデスクトップアプリの通知を送るには、通知センターの新しい項目を読み取ってntfyへPOSTするNotiFerryのようなブリッジが必要です。

NotiFerryがntfyへ送信するJSONペイロード

除外されていない新しい通知が届くたびに、NotiFerryは設定されたntfyサーバーのルートに対してJSON形式の POST リクエストを送信します：

POST https://ntfy.sh/
Content-Type: application/json

{
  "topic": "nf-…",
  "title": "<送信元アプリ名> — <通知タイトル>",
  "message": "<サブタイトルと本文>",
  "priority": 3,
  "tags": ["computer"]
}

送信されるテキストの範囲は、NotiFerryで選択したプライバシーモードによって決まります：

• 通知の全文（Full notification）： タイトルにアプリ名と通知タイトル、メッセージ本文にサブタイトルと本文が入ります。
• タイトルのみ（デフォルト）： タイトルにアプリ名と通知タイトルが入り、本文は New notification に置き換えられます。
• 汎用アラート（Generic alert）： アプリ名と New notification のみが送信されます。

セルフホスト型ntfyサーバーの利用と認証

デフォルトでは、NotiFerryは公開サービスの https://ntfy.sh と、nf- で始まるランダムな60文字（16進数）のトピック名を使用します。設定画面から、ご自身で運用するntfyサーバーのURLへいつでも切り替えられます。

• リモートサーバーには HTTPS が必須です（http:// はローカルテスト用の localhost または 127.0.0.1 のみ許可されます）。
• セルフホスト型サーバーからiPhoneのntfyアプリへバックグラウンドで即時プッシュ通知（APNs）を届けるには、ntfyのiOS設定ドキュメントに従い、サーバー側の server.yml に upstream-base-url: "https://ntfy.sh" を設定してください。
• 認証なしのほか、アクセストークン（Bearer）またはユーザー名とパスワード（Basic）に対応しており、認証情報はmacOSキーチェーンに安全に保存されます。サーバーURL・トピック・認証情報を変更した際は、iPhoneで新しいテスト通知の受信を確認するまで転送が自動的に一時停止されます。

レート制限・バースト集約・ローカル再送キュー

公開サービスの ntfy.sh（無料枠の上限は1日250通）を利用する場合、NotiFerryはレート制限に抵触しないよう1分あたり約12通のペースに送信を調整します。配信が30秒以上遅れている状態で同一アプリの未送信通知が5件以上溜まると、最新1件にまとめて「直前の通知件数」を添えて送信します。

また、Macが一時的にオフラインになった場合やサーバーが 429 / 5xx を返した場合は、フィルタリング済みの通知を最大1,000件までローカルキューに保持し、最大1分間隔の指数バックオフで再試行します。発生から10分経っても送信できなかった古い通知は、遅れて届いて混乱を招くのを防ぐため自動的に破棄されます。