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

変更履歴

✨ 追加機能​

ドキュメントサイト​

サービス（12個）​

ブロック統合ガイド（18個）​

ブロックリファレンスページ（約82ページ）​

  • ソース検証済みの routes、schemas、features、handlers、validators、および blocks ページ。各ドメインの Reference map は正確なリストを記載（例：カテゴリと属性は blocks.md を省略、アイデンティティは handlers.md を省略、招待とOAuthはドメインバリデーターページを省略）。
  • バリデーター整合性: 13エンティティの validators.md ファイル across に標準化されたインベントリテーブル（アイデンティティ参照コントラクト）。
  • スキーマ整合性: ブロック schemas.md ファイルAcrossにセクション順序とインベントリテーブルを標準化; 共通スキーマ はネストされた blocks/common/schemas/ ページから単一リファレンスに統合。
  • 高トラフィックドメインの深層ルートおよびハンドラリファレンス（例: 認証ルート、製品ルート）。
  • 従来の blocks/user/ ドキュメントツリーを削除; blocks/profile/ に置き換え、完全なリファレンスページ付き。

コンポーネント、ユーティリティ、およびドライバーリファレンス​

リファレンスの深さと一貫性​

  • ブロック index.md コントラクトを統一: ここから始める → 一般的なタスク → Reference map → 関連モジュール、マウント可能サービスに対するBearer/Cookie/カスタムHTTPワークフロー例付き。
  • scripts/ に12個の整合性/監査スクリプト（align-*-md.mjs、audit-*-md.mjs）; 2個が package.json で align:index-md および audit:index-md として接続。

🔄 変更​

命名とインポート​

  • サービス、コレクション、ルート、および例全体で ユーザー → プロフィール（profileService、profiles コレクション、/profiles パス）。プロフィールサービス および プロフィールブロック を参照。
  • 従来の blocks/user/ ドキュメントツリーを削除; すべてのユーザードメインリファレンスは blocks/profile/ で管理。
  • 正規化された統合例では名前空間のみインポート: import { services, primitives, drivers, validators } from '@nodeblocks/backend-sdk'。フラットルートインポートと非推奨 userService 名は削除。

認証設定​

  • accessTokenSignOptions、refreshTokenSignOptions、および onetimeTokenSignOptions を介してトークン生存期間を文書化（フラットexpiryキーに置き換え）。デフォルトアクセストークンの生存期間は 15分（従来の 2時間 デフォルトは非表示）。認証インデックス および auth ユーティリティ を参照。
  • Cookie 認証 (0.13.0): authMode: 'cookie'、ホスト cookie-parser、保護されたCRUDサービスごとの authMode、および cookie モードのログイン/リフレッシュ/logout レスポンス形状。cookie ユーティリティ を参照。

APIレスポンス形状​

  • ページネーションリストエンドポイントは { data, metadata: { pagination } } を返す（従来の { count, total, value } エンベロープに置き換え）。共通スキーマ を参照。

ハウツー、コンセプト、およびコンポーネント​

🐞 修正（ドキュメント修正）​

  • 設定命名: サービスおよび統合ガイドで identity.typeIds および関連認証設定例を従来の user.typeIds パターンから修正。
  • リクエストとレスポンスコントラクト: サービスおよびルートページはソース監査後に更新（組織メンバー、認証logout/メールテンプレート、注文管理者作成、製品および組織リストエンベロープ、チャット添付ファイル、および関連例）。
  • 変更メール動作: 列挙強化フローが 認証ルート で mapMatchingErrorToFalse とともに文書化。

SDK 0.13.0 (2026-07-14)​

✨ 追加機能​

サービス​

  • 保護されたCRUD/ドメインサービス設定に authMode?: 'bearer' | 'cookie' をオプションで追加（属性、プロフィール、製品、カテゴリ、組織、場所、注文、チャット、アイデンティティ、通知、住所）。authMode が 'cookie' の場合、各サービスは getCookieTokenInfo を context.authenticate に接続; それ以外の場合は getBearerTokenInfo を使用。認証サービス およびマウント可能ドメイン統合ガイドを参照。

認証​

  • checkIp?: boolean（デフォルト true）を AuthenticationServiceConfiguration に追加; getBearerTokenInfo と getCookieTokenInfo の両方がこのオプションを取得。認証サービス を参照。
  • whenCookieAuth ユーティリティ（utils からエクスポート）は authMode に基づいて合成ハンドラを cookie モードと bearer モードの実装間で分岐します。
  • context.authenticate の型付きフィールドが ServiceContext / ServiceDefinition に追加され、authMode に応じて getCookieTokenInfo または getBearerTokenInfo で設定されます。
  • スタンドアロンの logoutFeature。authMode に応じて logoutCookieSchema または logoutBearerSchema をコンパイル時に選択。
  • refreshTokenBearerSchema と refreshTokenCookieSchema; refreshTokenSchema は refreshTokenBearerSchema の非推奨エイリアスとして残る。
  • cookieOpts.httpOnly と cookieOpts.secure が設定可能に（従来はハードコード true）。

🔄 変更​

認証​

  • セッションクッキーの maxAge はクッキー設定時に各トークンの expiresIn（accessTokenSignOptions / refreshTokenSignOptions）から自動的に算出されるため、クッキーとトークンは常に同時に期限切れになる。
  • loginWithCredentialsRoute: cookie モードはレスポンス本文に { id } のみを返す; トークンは Set-Cookie で配信。bearer モードは変更なし（{ accessToken, id, refreshToken }）。
  • refreshTokenRoute: cookie モードは更新されたクッキーを設定し 204 と空の本文を返す; bearer モードは変更なし（200 { accessToken, refreshToken }）。
  • setResponseCookie は単一のオプションセットを共有するのではなく、accessTokenSignOptions.expiresIn / refreshTokenSignOptions.expiresIn からアクセストークンおよびリフレッシュトークンのクッキーオプションをそれぞれ独立して算出する。

🐞 修正​

認証​

  • logoutRoute: リクエストに refreshToken クッキーがあった場合に限らず、accessToken と refreshToken クッキーを無条件に消去; 呼び出し者のアイデンティティを context.authenticate（cookieまたはbearer対応）経由で解決; すでに取り消されたリフレッシュトークンをエラーではなく成功として扱う; リゾルブできないリフレッシュトークンの場合もエラーではなく成功として扱う。
  • deactivateRoute: cookie モードでアクセストークンを Authorization ヘッダーではなく accessToken クッキーから読み取る。

組織​

  • createChangeRequestRoute: cookie モードでアクセストークンを Authorization ヘッダーではなく accessToken クッキーから読み取る。

🔒 セキュリティ​

  • getCookieTokenInfo の undocumented バイパスを削除し、appタイプの Authorization: Bearer トークンがcookie/セッション検証を完全にスキップできるようにした。
  • getCookieTokenInfo はもはや checkIp: false をハードコードしません; cookie認証されたユーザートークンはbearerトークンと同様にIPチェックがデフォルトで有効。

📦 マイグレーション​

  • Cookie認証ホスト: 認証サービスだけに authMode: 'cookie' を設定するだけでは不十分です。cookieセッションを受け付けるすべてのマウント済み保護サービスに authMode: 'cookie' を渡し、cookie-parser ミドルウェアを登録してください。
  • Cookieモードクライアント: POST /auth/login および POST /auth/token/refresh では、アクセストークン／リフレッシュトークンをレスポンス本文ではなく Set-Cookie レスポンスヘッダーから読み取ってください。
  • 手動の loginWithCredentialsFeature 合成: POST /auth/logout を維持するには logoutFeature を明示的に追加してください（authService ファクトリはこれを自動で行います）。
  • アクセストークンの有効期間: デフォルトの 2h アクセストークン有効期間に依存していた場合は、accessTokenSignOptions: { expiresIn: '2h' } を明示的に設定してください — デフォルトは現在 15m です。
  • Cookie認証のIPチェック: デプロイ環境でクライアントIPがリクエスト間で正当に変わる場合（一部のプロキシやモバイルネットワークなど）は、AuthenticationServiceConfiguration で checkIp: false を明示的に設定してください。
  • 削除されたバリデーター: validateResourceAccess、validateOrganizationAccess、validateOrderAccess、validateMessageAccess、validateChannelAccess、verifyAuthentication、requireParam、isUUID、または isNumber の直接インポートを、現行の同等物（isAuthenticated、hasOrgRole、ownsResource、ownsOrder、ownsMessage、ownsChannel など）に置き換えてください。

⚠️ 破壊的変更​

  • 認証: AuthenticationServiceConfiguration.cookieOpts.maxAge が削除されました。クッキーの生存期間は一致するトークンの expiresIn に従います。cookieOpts.maxAge 設定を削除してください。
  • 認証: デフォルト accessTokenSignOptions.expiresIn が 2h から 15m に変更。
  • 認証: loginWithCredentialsFeature はもはや logoutRoute を合成しません。authService 外で loginWithCredentialsFeature に直接構築されたカスタム合成は、logoutFeature を個別に追加する必要があります。
  • 認証: Cookieモードのログインとリフレッシュはレスポンス本文にトークンを返さなくなりました。
  • 認証: getCookieTokenInfo はcookie認証へのバイパスパスとして Authorization: Bearer を受け付けなくなります。
  • バリデーター: 共通バリデーター から未使用のlegacyバリデーターエクスポートを削除: validateResourceAccess、validateOrganizationAccess、validateOrderAccess、validateMessageAccess、validateChannelAccess、verifyAuthentication、requireParam、isUUID、および isNumber。

SDK 0.12.0 (2026-07-07)​

🐞 修正​

認証​

  • completePasswordResetRoute: ユーザーがパスワードをリセットしたときに、すべてのアクティブなリフレッシュトークンを撤销し、すべてのデバイスで既存のセッションを終了。
  • changePasswordRoute: ユーザーがパスワードを変更したときに、すべてのアクティブなリフレッシュトークンを撤销。
  • 指紋セキュリティチェック: tokenPassesSecurityCheck は undefined と '' を同等として扱います; トークン生成は生成時点で指紋を '' に正規化。
  • logoutRoute: リフレッシュトークンの撤销が成功した場合のみ、認証トークンクッキーを消去。

🔄 変更​

認証​

  • softDeleteRefreshTokens は delFlg の代わりに deletedAt を設定し、リフレッシュトークンの撤销チェックと整合。
  • refreshTokenRoute: 各使用時にリフレッシュトークンを回転（新しい jti + DB行）; 取り消されたリフレッシュトークンの再利用に対して 401 を返す（他のデバイスのセッションを取り消さず）; cookie/本文解決のために resolveRefreshTokenFromRequest を使用。
  • logoutRoute: 認証されたアイデンティティに属することを確認した後、提示されたリフレッシュトークン（cookieまたは本文）を取り消す。
  • cookieベースのリフレッシュは指紋を x-nb-fingerprint ヘッダーから読み取る（本文パスと同じ）し、IP/UAチェックを実行。cookie ユーティリティ を参照。

⚠️ 破壊的変更​

  • cookieベースのリフレッシュ (refreshTokenRoute) および cookieベースのlogout (logoutRoute) は x-nb-fingerprint ヘッダーを必要とする。cookieパス上では request.body.fingerprint はもはや読み取られない。

SDK 0.11.0 (2026-05-26)​

✨ 追加機能​

コンビネーター​

  • mapMatchingErrorToFalse: 特定のエラークラスを ok(false) にマッピングする（従来の mapErrorToFalse はすべてのエラーを変換）。

🔄 変更​

プロフィール（旧ユーザー）​

  • ユーザーハンドラ、ブロック、ルート、スキーマ、フィーチャ、およびサービス名をプロフィールに変更。プロフィールサービス および プロフィールブロック を参照。
  • 組織および製品ルートおよびサービスで users コレクション参照を profiles に更新。
  • 非推奨 validateUserProfileAccess バリデーターを削除。
  • getProfileById の戻り型を更新。

🔒 セキュリティ​

メール変更​

  • changeEmailRoute: リクエストされたメールアドレスが既に使用されている場合に、エラーの代わりに 204 を返し、メールの列挙を防ぐ。
  • 競合エラーのみを ok(false) に変換するために mapMatchingErrorToFalse を使用。

⚠️ 破壊的変更​

  • プロフィールリネーム: user サービス、ルート、ブロック、スキーマ、およびフィーチャは profile にリネームされました。すべてのインポートを user* から profile* に更新してください。
  • バリデーター: validateUserProfileAccess が削除されました。代わりに更新された プロフィールバリデーター を使用してください。
  • コンビネーター: mapErrorToFalse は mapMatchingErrorToFalse にリネームされ、第一引数としてエラークラスを必要とします。

SDK 0.10.0 (2026-03-17)​

✨ 追加機能​

通知管理​

  • 新サービス: 通知サービス。
  • 新規エンドポイント:
    • GET /notifications/identities/:identityId — ページネーション付きで通知を検索。通知ルート を参照。
    • POST /notifications/:notificationId/read — 単一通知を読としてマーク。
    • POST /notifications/identities/:identityId/read — アンカー通知までバッチで読としてマーク。
  • 作成、バッチ作成、検索、取得、単一更新、およびバッチ更新操作のための通知ブロック。

住所検索​

組織メンバー保護​

  • 組織から最後のオーナーを削除できないようにするバリデーター。
  • メンバーが自身の階層より上の役割を割り当てられないようにする役割割り当て検証。
  • 組織メンバーを削除する前に同以上役割の検証。組織バリデーター を参照。

🐞 修正​

アイデンティティ​

  • getIdentityRoute: identities コレクションに保存されたトークン記録を除外し、一致するトークンレコードを防ぐ（jti のドキュメントを除く）。

住所検索​

  • Japan Post 郵便番号処理は検索時に完全な7桁のコードを必要とする。
  • 複数の町が同じ郵便番号を共有する場合、推測するのではなく null を返す。

🔄 変更​

認証設定​

  • ストリングベースの有効期限設定を accessTokenSignOptions、refreshTokenSignOptions、および onetimeTokenSignOptions に置き換え。認証サービス および auth ユーティリティ を参照。
  • パスワードリセット、メール変更、MFA、およびOAuthフロー全体で共有のワンタイムトークン署名オプションを適用。

認可ルール​

  • 組織メンバーのアップsert および削除ルートに追加の役割階層チェックを追加。

SDK 0.9.1 (2026-01-22)​

✨ 追加機能​

認証​

  • 新しいパスワードが現在のパスワードと同じでないかを確認するパスワード検証。
  • 個別のbcrypt比較と一致ロジックを2つのブロックに分割; password-must-not-matchフローのための新しい assertDoesNotMatch ブロック。

スキーマ検証​

  • applySchemaDefaults でオブジェクト関連キーワードを含むタイプなしスキーマの処理。
  • スキーマ検証でのオブジェクトを含むユニオンタイプのサポート。

🔄 変更​

  • タグ伝播と Nullable スキーマサポートを改善したOpenAPIスキーマ生成を強化。

🔒 セキュリティ​

SDK 0.9.0 (2025-11-04)​

✨ 追加機能​

場所管理​

  • 新サービス: 場所サービス。
  • 新規エンドポイント: POST /locations、GET /locations/:locationId、PATCH /locations/:locationId、DELETE /locations/:locationId、GET /locations。場所ルート を参照。
  • 自動祖先計算による親子関係の処理。

プロフィールフォローシステム​

  • 新規エンドポイント:
    • PUT /profiles/:profileId/profile-follows/:followProfileId — プロフィールフォローを作成。プロフィールルート を参照。
    • DELETE /profiles/:profileId/profile-follows/:followProfileId — プロフィールフォローを削除。
    • GET /profiles/:profileId/followers — ページネーション付きでプロフィールのフォロワーを取得。

組織フォローシステム​

  • 新規エンドポイント:
    • PUT /profiles/:profileId/organization-follows/:followOrganizationId — 組織フォローを作成。
    • DELETE /profiles/:profileId/organization-follows/:followOrganizationId — 組織フォローを削除。
    • GET /organizations/:organizationId/followers — 組織のフォロワーを取得。組織ルート を参照。

製品いいねシステム​

  • 新規エンドポイント:
    • PUT /profiles/:profileId/product-likes/:likeProductId — 製品いいねを作成。
    • DELETE /profiles/:profileId/product-likes/:likeProductId — 製品いいねを削除。
    • GET /products/:productId/likers — 製品のいいねをするユーザーを取得。製品ルート を参照。

チャットメッセージテンプレート管理​

製品バリエーション一括操作​

  • 新規エンドポイント:
    • POST /products/:productId/variants/bulk、PATCH /products/:productId/variants/bulk、DELETE /products/:productId/variants/bulk、GET /products/:productId/variants。製品ルート を参照。

検索エンドポイント​

  • GET /profiles/identities/:identityId — アイデンティティIDでプロフィールを検索。
  • GET /organizations/:organizationId/orders — 組織IDで注文を検索。
  • GET /organizations/:organizationId/products — 組織IDで製品を検索。

アイデンティティロック/アンロック​

チャットチャンネルアイコン管理​

ソフト削除​

  • MongoDBコレクションの withSoftDelete コンビネーター（自動フィルタリングと監査証跡付き）。

🐞 修正​

  • すべての作成および更新操作に updatedAt/createdAt タイムスタンプを追加。
  • セキュリティのためにすべてのデータベースクエリでIDを文字列にキャスト。

🔄 変更​

  • チャットメッセージの更新はメッセージ所有者のみ（管理者オーバーライドを削除）。updateChatMessageRoute を参照。
  • エンティティ作成を簡素化: メッセージと製品は添付ファイル/画像なしで作成; 添付ファイルは専用エンドポイント経由で管理。

SDK 0.8.0 (2025-09-24)​

✨ 追加機能​

製品バリエーション管理​

  • 新規エンドポイント:
    • POST /products/:productId/variants — 製品バリエーションを作成。
    • GET /products/:productId/variants/:productVariantId — IDで製品バリエーションを取得。
    • PATCH /products/:productId/variants/:productVariantId — 製品バリエーションを更新。
    • DELETE /products/:productId/variants/:productVariantId — 製品バリエーションを削除。
  • 製品フィーチャ および 製品ルート を参照。

組織変更リクエストシステム​

組織管理​

  • updateOrganizationAsAdminRoute: PATCH /admin/organizations/:organizationId/。
  • 認証画像URLが正規化された組織レスポンスに追加。

マルチファクター認証（MFA）​

ワンタイムトークン（OTT）認証​

  • loginWithOnetimeTokenRoute: POST /auth/ott/login。
  • OAuthコールバックフローはワンタイムトークンを返す; フロントエンドはOTTログインエンドポイント経由で交換。

ページネーションシステム​

  • PaginationResult<T> をデータとメタデータに分離するように再構造化。
  • リストエンドポイントは { data, metadata: { pagination } } を返す（従来の { count, total, value } に置き換え）。
  • 標準クエリパラメータとメタデータの paginationQueryParametersSchema と paginationSchema。
  • findOrganizationMembersRoute: withPaginatedProperty 経由で埋め込みページネーション。

🐞 修正​

  • WebSocketリクエストのWebSocket IPアドレスの可用性。
  • ページネーションメタデータの戻り問題。

SDK 0.7.0 (2025-09-12)​

✨ 追加機能​

チャットメッセージ添付ファイル​

チャットチャンネルメッセージ​

チャット既読受信​

チャットWebSocket購読​

  • streamChatMessagesRoute: リアルタイムメッセージストリーミングのための WebSocket /messages/listen。

LINE OAuth認証​

製品画像管理​

  • 新規エンドポイント:
    • POST /products/:productId/images — 製品画像を作成。
    • DELETE /products/:productId/images/:imageId — 製品画像を削除。
  • 製品ルート を参照。

ブロック​

  • チャット状態ブロック: createChatChannelReadState、updateChatChannelReadState、findChatChannelReadStates、およびクエリ/ペイロードビルダー。
  • チャットメッセージブロック: createChatMessage、getChatMessageById、添付ファイルCRUD、および正規化ヘルパー。
  • 製品ブロック: getProductById、findProducts、画像正規化ヘルパー。
  • OAuthブロック: requestLineOAuth、authenticateLineOAuth、verifyLineOAuth。
  • normalizeFile: 集中ファイル正規化ユーティリティ。

🔄 変更​

  • チャットと製品の正規化は集中的な normalizeFile ユーティリティを使用するようにリファクタリング。
  • エンティティ作成を簡素化: コアメッセージと製品は添付ファイル/画像なしで作成; 添付ファイルは専用エンドポイント経由で管理。

🐞 修正​

  • チャット添付ファイルの正規化（更新レスポンス内）; セキュリティIDのキャスト; 添付ファイル操作の管理者アクセス制限。
  • OAuth: GoogleとTwitterフローはemailワークアラウンドの代わりに provider/providerId を使用するように修正。

SDK 0.6.0 (2025-08-28)​

🎥 デモ動画​

📹 NodeBlocks Backend SDK v0.6.0 デモ — すべての新機能と機能の完全なウォークスルー。

✨ 追加機能​

チャットメッセージテンプレートシステム​

Twitter OAuth認証​

リフレッシュトークンシステム​

RxJSによるWebSocketサポート​

  • defService を強化し、WebSocketサーバー統合をサポート。
  • RxJS ブリッジによる WebSocket ルート処理。protocol: 'ws' ルートを HTTP ルートと並行して扱います。
  • notFromEmitter および markAsFromEmitter はエミッターベースのメッセージフィルター用です。

🔄 変更​

サービス​

  • 認証サービス: Twitter OAuthサポートとリフレッシュトークン機能を追加; データストアに chatMessageTemplates コレクションを含めるように更新。

🐞 修正​

  • 組織ブロックのエクスポート問題。
  • refreshTokenRoute: リフローフローから isAuthenticated バリデーターを削除。
  • 設定プロパティ名を修正（user.typeIds → identity.typeIds; user?: string → regular?: string）。

マイグレーションガイド（0.6.x ドキュメントからアップグレード）​

  1. @nodeblocks/backend-sdk@^0.13.0 をインストールし、クイックスタート に従う。
  2. userService、/users、および users コレクションの例を profileService、/profiles、および profiles に置き換え。
  3. フラットトークンの有効期限キーを accessTokenSignOptions、refreshTokenSignOptions、および onetimeTokenSignOptions に置き換え。2時間 のアクセストークンが必要な場合は accessTokenSignOptions: { expiresIn: '2h' } を明示的に設定。
  4. cookieセッションの場合、マウントするすべての保護されたサービスに authMode: 'cookie' を設定し、それらのルーターの前に cookie-parser を登録し、ログイン/リフレッシュ時にJSON本文ではなく Set-Cookie からトークンを読み取る。
  5. 削除されたバリデーターインポート（validateResourceAccess、verifyAuthentication、requireParam など）を 共通バリデーター とドメインバリデーターページに記載されている現在のエクスポートに置き換え。
  6. ブロックカタログ とドメイン Reference map テーブルを使用して、各エンドポイントの現在のルート、スキーマ、およびバリデーターコントラクトを見つける。
  7. cookieモードのリフレッシュとlogoutリクエストに x-nb-fingerprint ヘッダーを送信（SDK 0.12.0）。
  8. authService 外で loginWithCredentialsFeature に構築されたカスタム合成に logoutFeature を追加（SDK 0.13.0）。
  9. cookieOpts.maxAge を削除; クッキーの生存期間は一致するトークンの expiresIn に従う（SDK 0.13.0）。
  10. mapErrorToFalse を mapMatchingErrorToFalse(errorClass, [...]) に置き換え（SDK 0.11.0）; 合成ユーティリティ を参照。

破壊的ドキュメント変更​

  • バージョン指定スナップショットは backend_versioned_docs/version-0.6.0 および version-0.7.0 に歴史的参照として残ります。新しい統合では canary v2 ドキュメント /v2/backend/next を使用すべきです。
  • 例はもはやフラットSDKインポート、user* サービス名、または従来のページネーションエンベロープを表示しない。
  • cookieモードのログインとリフレッシュの例は、レスポンス本文にアクセスまたはリフレッシュトークンを返さなくなります; クライアントはセッションクッキーを使用する必要があります。

セキュリティドキュメント更新​

  • cookie認証はcookie保護ルートにundocumented Bearerバイパスを文書しなくなりました; IPチェックは有効デフォルトで checkIp が有効になっています。認証サービス を参照。
  • 変更メールレスポンスは列挙エラーの代わりに 204 を文書化してメールの列挙を減らします; 認証ルート を参照。
  • 組織メンバー保護、通知所有権、および住所検索検証は、それぞれの バリデーター および ルート ページに現在のアクセスルールとともに文書化。