TypeScript SDK

@todoke/sdk を使うと、購読登録から通知送信まで数行で実装できます。

インストール

ノート

@todoke/sdk は現時点で npm に公開されていません。リポジトリを clone し、bun install の後 cd packages/sdk && bun run build でビルドして使用してください。以下のインストールコマンドは npm 公開後に有効になります。

npm

npm install @todoke/sdk

bun

bun add @todoke/sdk

pnpm

pnpm add @todoke/sdk

クライアントの初期化

import { PushCF } from "@todoke/sdk";

const client = new PushCF({
  apiKey: "pk_your_key",
  // baseUrl: "https://api.todoke.dev" // デフォルト値
});

メソッドリファレンス

PushCF インスタンスは以下の 3 つのメソッドを提供します。

メソッド	説明	必要スコープ
notify(payload: NotifyPayload): Promise<void>	通知を送信する（POST /api/v1/notify）	notify 以上
subscribe({ registration }: SubscribeOptions): Promise<void>	ブラウザの Push 購読を登録する	subscribe_only 以上
getStats(): Promise<Stats>	統計情報を取得する（GET /api/v1/stats）	notify 以上

ノート

「notify 以上」は notify または full スコープを、「subscribe_only 以上」は subscribe_only / notify / full のいずれのスコープでも呼び出せることを意味します。スコープの詳細は API キー を参照してください。

購読登録

// Service Worker の準備（事前に /sw.js を配置）
const registration = await navigator.serviceWorker.ready;

// 購読登録（ブラウザ通知許可ダイアログが表示される）
await client.subscribe({ registration });

内部動作

subscribe は内部で次の 3 段階の処理を順に行います。

1. GET /api/v1/vapid-public-key を呼び出し、アプリの VAPID 公開鍵を取得する
2. 取得した鍵を applicationServerKey として registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey }) を呼び出す（ここでブラウザの通知許可ダイアログが表示される）
3. 作成された購読情報（endpoint / p256dh / auth）を POST /api/v1/subscriptions でサーバーに登録する

注意

subscribe を呼び出す前に、Service Worker の登録が完了している必要があります（navigator.serviceWorker.register(...) の完了を待った navigator.serviceWorker.ready の解決値を registration に渡してください）。未登録の状態で呼び出すと pushManager.subscribe が失敗します。

通知送信

// 全購読者へ送信
await client.notify({
  title: "お知らせ",
  body: "新しいメッセージがあります",
  url: "https://yourapp.com/messages",
  icon: "https://yourapp.com/icon.png",
});

// 特定の購読者へ送信
await client.notify({
  title: "あなた宛",
  body: "個別通知",
  endpoint: "https://push.example.com/specific-endpoint",
});

統計情報

const stats = await client.getStats();
// {
//   activeSubscribers: number,
//   totalSent: number,
//   totalFailed: number,
//   monthlySent: number
// }

エラーハンドリング

notify / subscribe / getStats はいずれも、API がエラーレスポンスを返すと PushCFError を throw します。PushCFError は status（HTTP ステータスコード）と code（API のエラーコード文字列。エラーコード一覧を参照）のプロパティを持ちます。

import { PushCF, PushCFError } from "@todoke/sdk";

try {
  await client.notify({ title: "テスト", body: "送信" });
} catch (err) {
  if (err instanceof PushCFError) {
    console.error(`[${err.code}] ${err.message} (status: ${err.status})`);
  }
}

典型的なエラーコードで処理を分岐する例:

import { PushCF, PushCFError } from "@todoke/sdk";

try {
  await client.notify({ title: "hi", body: "yo" });
} catch (err) {
  if (err instanceof PushCFError && err.code === "MONTHLY_LIMIT_EXCEEDED") {
    // 月間上限。翌月まで待つかプランをアップグレード
  }
}

ノート

subscribe が pushManager.subscribe の返す購読情報に endpoint / p256dh / auth のいずれかが欠けていると判断した場合は、API を呼び出す前に status: 0・code: "INVALID_SUBSCRIPTION" の PushCFError を throw します（ネットワークエラーではなくクライアント側の検証エラーです）。

型定義

type PushCFOptions = {
  apiKey: string;
  baseUrl?: string; // 省略時は "https://api.todoke.dev"
};

type NotifyPayload = {
  title: string;
  body: string;
  url?: string;      // https:// のみ
  icon?: string;     // https:// のみ
  badge?: string;    // https:// のみ
  endpoint?: string; // 指定時は特定購読者のみ
};

type SubscribeOptions = {
  registration: ServiceWorkerRegistration; // 登録済みの Service Worker
};

type Stats = {
  activeSubscribers: number;
  totalSent: number;
  totalFailed: number;
  monthlySent: number;
};