バージョン: 0.13.0 (Previous)

🔔 通知

通知は、notifications コレクションに対する、認証済みで受信者スコープの一覧表示および既読化操作を提供します。

ここから始める

notificationService には identities、notifications、トークン用シークレットが必要です。既定ではベアラー認証を使用します。defService はルーター固有の JSON パーサーも登録します。以下のホストレベルパーサーはこれらのルートでは任意ですが、ホストにほかの JSON エンドポイントがある場合も安全かつ有用です。

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

const app = express();
app.use(express.json());
app.use(
  '/api',
  services.notificationService(
    {identities, notifications},
    {authSecrets: {authEncSecret: 'replace-me', authSignSecret: 'replace-me'}},
  ),
);

構成	デフォルト / ソース動作	効果
`dataStores.identities`	`NotificationServiceDataStore` では必須。現在のルートは読み取りません	サービスの TypeScript 契約を満たします。
`dataStores.notifications`	必須	すべてのルートが読み取り、既読化する 2 つのルートが更新します。
`configuration.authSecrets`	必須	選択されたアクセストークンアダプターがこれらのシークレットでトークンを復号・検証します。
`configuration.authMode`	省略時または `'bearer'` は `Authorization: Bearer <token>` ヘッダーを読み取る	`'cookie'` は `request.cookies.accessToken` を読み取ります。

Cookie モードでは、サービスルーターより前にホスト側で cookie-parser を登録する必要があります。ユーザートークンでは、どちらのアダプターも常にリクエストフィンガープリントを比較します。既定の checkIp: true では、IP が不一致でもユーザーエージェントも異なる場合にのみ失敗します。リクエストホストは読み取りますが、現在のチェックでは比較しません。トランスポート用ヘルパーは認証ユーティリティと Cookie ユーティリティを参照してください。

よくあるタスク

タスク	開始点	契約
1 つのアイデンティティの通知を一覧	`findNotificationsFeature`	`findNotificationsRoute`、`findNotificationsSchema`、`isSelf` による本人アクセス
1 件の通知を既読にする	`updateNotificationToReadFeature`	`updateNotificationToReadFeature`、`updateNotificationToReadRoute`、`updateNotificationToReadSchema`。呼び出し元が通知の所有者である必要があります。
アンカーを通じて通知を既読にする	`updateNotificationToReadBatchFeature`	`updateNotificationToReadBatchFeature`、`updateNotificationToReadBatchRoute`、`updateNotificationToReadBatchSchema`

通知には公開 HTTP ルートがありません。すべてのエンドポイントで最初に isAuthenticated() を実行します。一覧および一括ルートでは、対象の identityId が呼び出し元自身であることも必要です。単一既読ルートでは、呼び出し元が通知の所有者である必要があります。

Bearer HTTP ワークフロー

本文なしで Authorization: Bearer <access-token> を付けて POST /api/notifications/notification-1/read を送信します。updateNotificationToReadRoute は受信者に空の 204 を返します。所有者でない場合は ownsNotification で失敗し、通知が見つからない場合も、ルート後段の 404 マッピングより前にこのバリデーターで 403 Invalid owner ID となります。

呼び出し元自身の通知を一覧するには、同じヘッダーで GET /api/notifications/identities/identity-1?page=1&limit=10 を送信します。findNotificationsRoute は { data, metadata: { pagination } } を含む 200 を返します。パス内のアイデンティティが異なる場合は 403 です。

export API_BASE_URL='http://localhost:8080/api'
export ACCESS_TOKEN='replace-with-a-valid-access-token'
export IDENTITY_ID='identity-1'
export NOTIFICATION_ID='notification-1'

curl -X POST "$API_BASE_URL/notifications/$NOTIFICATION_ID/read" \
  -H "authorization: Bearer $ACCESS_TOKEN"

curl "$API_BASE_URL/notifications/identities/$IDENTITY_ID?page=1&limit=10" \
  -H "authorization: Bearer $ACCESS_TOKEN"

authMode: 'cookie' を設定し、サービスルーターより前に cookie-parser を登録してから、ベアラーヘッダーではなく accessToken Cookie で同じ保護されたリクエストを送信します。Cookie がない場合は、選択されたアダプターで 401 Unable to detect access token となります。既読化が成功した場合は空の 204 を返します。

export API_BASE_URL='http://localhost:8080/api'
export ACCESS_COOKIE='accessToken=replace-with-a-valid-access-token'
export NOTIFICATION_ID='notification-1'

curl -X POST "$API_BASE_URL/notifications/$NOTIFICATION_ID/read" \
  -H "cookie: $ACCESS_COOKIE"

カスタム機能合成

このベアラーモードの断片は、サービスソースと同じ SDK コンポーザーを使用します。以下の identities と notifications は MongoDB コレクションです。3 つのフィーチャーをソース順にマウントし、一覧ルートは本人専用、すべてのルートは認証済みのままです。

import {partial} from 'ramda';
import {features, primitives, utils} from '@nodeblocks/backend-sdk';

const dataStores = {identities, notifications};
const configuration = {
  authSecrets: {
    authEncSecret: 'replace-me',
    authSignSecret: 'replace-me',
  },
};
const router = primitives.defService(
  partial(
    primitives.compose(
      features.updateNotificationToReadFeature,
      features.findNotificationsFeature,
      features.updateNotificationToReadBatchFeature,
    ),
    [{authenticate: utils.getBearerTokenInfo, configuration, dataStores}],
  ),
);
app.use('/api', router);

リファレンスマップ

ページ	目的
Blocks	通知の永続化、一覧、既読化操作。
Features	サービスがマウントするスキーマからルートへのコンポーザー。
Routes	エンドポイント、アクセス、レスポンスの契約。
Schemas	リクエスト検証の契約。
Validators	認証、本人確認、所有権のガード。

ここから始める​

よくあるタスク​

Bearer HTTP ワークフロー​

Cookie HTTP ワークフロー​

カスタム機能合成​

リファレンスマップ​

関連モジュール​

ここから始める

よくあるタスク

Bearer HTTP ワークフロー

Cookie HTTP ワークフロー

カスタム機能合成

リファレンスマップ

関連モジュール