メインコンテンツまでスキップ
バージョン: 0.13.0 (Previous)

🔔 通知サービス

通知サービス（notificationService）は、アイデンティティの通知一覧と既読状態更新のエンドポイントを提供します。このサービスには通知を作成する HTTP API はありません。アプリケーション（または他のブロック）が通知ドキュメントを直接書き込みます。

🚀 クイックスタート​

import express from 'express';
import {middlewares, services, drivers} from '@nodeblocks/backend-sdk';

const {nodeBlocksErrorMiddleware} = middlewares;
const {notificationService} = services;
const {withMongo} = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

express()
  .use(
    notificationService(
      {
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('notifications')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // または 'cookie'
      },
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

🍪 Cookie 認証: authMode: 'cookie' の場合、保護されたルートは Cookie からアクセストークンを読み取ります。ホストアプリは cookie-parser を登録する必要があります。

📋 エンドポイント概要​

メソッドパス説明認可
POST/notifications/:notificationId/read1 件の通知を既読にするBearer／Cookie 認証。通知を所有している必要があります。
GET/notifications/identities/:identityIdアイデンティティの通知を一覧表示Bearer／Cookie 認証。本人のみ。
POST/notifications/identities/:identityId/readアンカーまでの通知を既読にするBearer／Cookie 認証。本人のみ。

このサービスは通知作成用 HTTP エンドポイントを公開しません。アプリケーションは独自の内部ロジックで通知レコードを作成します。

🗄️ エンティティスキーマ​

{
  "id": "string",
  "receiverId": "string",
  "isRead": "boolean",
  "createdAt": "string (datetime)",
  "updatedAt": "string (datetime)"
}
フィールド型説明
idstring通知識別子
receiverIdstring通知を受け取るアイデンティティ
isReadboolean通知が既読かどうか
createdAtdatetime作成タイムスタンプ
updatedAtdatetime最終更新タイムスタンプ

追加ペイロードフィールドは、アプリケーションによる通知作成方法に応じて存在する場合があります。

🔐 認証ヘッダー​

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

ログイン時にフィンガープリントが指定された場合、認証済みリクエストには x-nb-fingerprint ヘッダーが必要です。

🔧 API エンドポイント​

1. 通知を既読にする​

リクエスト:

  • メソッド: POST
  • パス: /notifications/:notificationId/read
  • 認可: 通知の認証済み所有者

パスパラメーター:

フィールド型必須説明
notificationIdstring✅通知 ID

レスポンス: 204 No Content

エラー: 所有権バリデーターはハンドラーより前に実行されます。有効な receiverId のない通知は 403 Invalid owner ID を返します。他の所有権失敗も 403 です。

例:

curl -X POST {{host}}/notifications/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/read \
  -H "Authorization: Bearer <access-token>"

2. アイデンティティの通知を一覧表示する​

リクエスト:

  • メソッド: GET
  • パス: /notifications/identities/:identityId
  • 認可: 認証済み本人（identityId はトークンの subject と一致する必要があります）

パスパラメーター:

フィールド型必須説明
identityIdstring✅受信者アイデンティティ ID

クエリパラメーター:

フィールド型必須説明
pagenumber❌ページ番号（1～1000）
limitnumber❌ページサイズ（1～50）

レスポンス: ページネーションエンベロープを含む 200 OK。

{
  "data": [
    {
      "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
      "receiverId": "f792cde5-958b-49e9-bf83-13d59c1e35c0",
      "isRead": false,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

例:

curl "{{host}}/notifications/identities/f792cde5-958b-49e9-bf83-13d59c1e35c0?page=1&limit=20" \
  -H "Authorization: Bearer <access-token>"

エラー: identityId が認証済みアイデンティティと異なる場合は 403 Identity ID does not match、無効な認証は 401 です。

3. 通知を一括既読にする​

指定されたアンカー通知まで（アンカーを含む）のアイデンティティ未読通知を既読にします。

リクエスト:

  • メソッド: POST
  • パス: /notifications/identities/:identityId/read
  • 認可: 認証済み本人

パスパラメーター:

フィールド型必須説明
identityIdstring✅受信者アイデンティティ ID

リクエスト本文:

フィールド型必須説明
lastReadNotificationIdstring✅アンカー通知 ID

レスポンス: 204 No Content

エラー: アンカー通知がない場合は 404。予期しない失敗では 500 が返る場合があります。

例:

curl -X POST {{host}}/notifications/identities/f792cde5-958b-49e9-bf83-13d59c1e35c0/read \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"lastReadNotificationId":"7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2"}'

⚙️ 構成オプション​

interface NotificationServiceConfiguration {
  authSecrets: {
    authEncSecret: string;
    authSignSecret: string;
  };
  authMode?: 'bearer' | 'cookie';
}

データストア​

コレクション必須説明
identities✅アイデンティティ検索／認証コンテキスト
notifications✅通知ドキュメント

🔗 関連ドキュメント​