Changelog

✨ Added

Documentation site

• Overview: layered architecture, namespace exports, composition patterns, and links to all major sections.
• Quickstart: end-to-end bootstrap with authService and profileService against SDK 0.13.0.
• Concepts: error handling and functional programming.
• How-to guides: custom service, composite service, custom datastore, WebSocket service, and schema override.
• Components: service, schema, handler, route, feature, blocks, validator, middleware, types, and driver references.
• Block catalogue: responsibility tables for all 18 block domains and how reference pages fit together.

Services (12)

• Authentication, Profile, Identity, Organization, Product, Order, Category, Attribute, Chat, Location, Address, and Notification.

Block integration guides (18)

• Mountable services: Authentication, Profile, Identity, Organization, Product, Order, Category, Attribute, Chat, Location, Address, and Notification.
• Auth-composed: OAuth and Invitation.
• Foundation modules: Common, Mongo, File Storage, and Avatar.

Block reference pages (~82 pages)

• Source-verified routes, schemas, features, handlers, validators, and blocks pages where the SDK exports that layer; each domain Reference map lists its exact set (for example, Category and Attribute omit blocks.md; Identity omits handlers.md; Invitation and OAuth omit domain validator pages).
• Validators alignment: standardized inventory tables across 13 entity validators.md files (identity reference contract).
• Schemas alignment: standardized section order and inventory tables across block schemas.md files; Common schemas consolidated from nested blocks/common/schemas/ pages into a single reference.
• Deep route and handler references for high-traffic domains (for example, Authentication routes, Product routes).
• Removed legacy blocks/user/ documentation tree; replaced by blocks/profile/ with full reference pages.

Component, utility, and driver reference

• Composition utilities: defService, WebSocket routing, withSoftDelete, and mapMatchingErrorToFalse.
• Auth, cookie, cache, and schema utilities: whenCookieAuth, cookie-mode branching, LRU caching, and query-filter hardening.
• New component pages: middleware and types.
• Route, schema, and blocks component pages aligned with SDK source patterns.
• Drivers index and references: drivers overview, mail-service, file-storage, database, OAuth, and Japan Post.

Reference depth and consistency

• Unified block index.md contract: Start here → Common tasks → Reference map → Related modules, with Bearer/Cookie/Custom HTTP workflow examples on mountable services.
• 12 alignment/audit scripts in scripts/ (align-*-md.mjs, audit-*-md.mjs); 2 wired in package.json as align:index-md and audit:index-md.

---

🔄 Changed

Naming and imports

• User → Profile across services, collections, routes, and examples (profileService, profiles collection, /profiles paths). See Profile service and Profile blocks.
• Removed the legacy blocks/user/ documentation tree; all user-domain reference now lives under blocks/profile/.
• Namespace-only imports in canonical integration examples: import { services, primitives, drivers, validators } from '@nodeblocks/backend-sdk'. Flat root imports and deprecated userService names are removed from those guides.

Authentication configuration

• Token lifetimes documented through accessTokenSignOptions, refreshTokenSignOptions, and onetimeTokenSignOptions (replacing flat expiry keys). Default access-token lifetime is 15m (older 2h defaults are no longer shown). See Authentication index and auth utility.
• Cookie auth (0.13.0): authMode: 'cookie', host cookie-parser, per-service authMode on protected CRUD services, and cookie-mode login/refresh/logout response shapes. See cookie utility.

API response shapes

• Paginated list endpoints document { data, metadata: { pagination } } instead of legacy { count, total, value } envelopes. See Common schemas.

How-to, concepts, and components

• Composite service, custom datastore, and related guides updated for Profile naming and current service factories.
• Error handling aligned with current NodeblocksError, BlockError, and Result patterns from source.
• Functional programming documents block-first composition versus legacy handler routes, with links to Route » Handler-based routes (legacy).

---

🐞 Fixed (documentation corrections)

• Configuration naming: identity.typeIds and related auth configuration examples corrected from legacy user.typeIds patterns in service and integration guides.
• Request and response contracts: service and route pages updated after source audits (organization members, auth logout/email templates, order admin create, product and organization list envelopes, chat attachments, and related examples).
• Change-email behavior: enumeration-hardening flow documented with mapMatchingErrorToFalse on Authentication routes.

---

SDK 0.13.0 (2026-07-14)

✨ Added

Services

• Optional authMode?: 'bearer' | 'cookie' on protected CRUD / domain service configurations (attributes, profile, product, category, organization, location, order, chat, identity, notification, address). When authMode is 'cookie', each service wires getCookieTokenInfo into context.authenticate; otherwise it uses getBearerTokenInfo. See Authentication service and mountable domain integration guides.

Authentication

• checkIp?: boolean (default true) on AuthenticationServiceConfiguration; both getBearerTokenInfo and getCookieTokenInfo honor this option. See Authentication service.
• whenCookieAuth utility (exported from utils) branches a composed handler between cookie-mode and bearer-mode implementations based on authMode.
• context.authenticate typed field on ServiceContext / ServiceDefinition, populated with getCookieTokenInfo or getBearerTokenInfo depending on authMode.
• Standalone logoutFeature, selecting logoutCookieSchema or logoutBearerSchema at compose time based on authMode.
• refreshTokenBearerSchema and refreshTokenCookieSchema; refreshTokenSchema remains as a deprecated alias for refreshTokenBearerSchema.
• cookieOpts.httpOnly and cookieOpts.secure are now configurable (previously hard-coded to true).

🔄 Changed

Authentication

• Session cookie maxAge is derived automatically from each token's expiresIn (accessTokenSignOptions / refreshTokenSignOptions) when cookies are set, so the cookie and token always expire together.
• loginWithCredentialsRoute: cookie mode returns only { id } in the response body; tokens are delivered via Set-Cookie. Bearer mode is unchanged ({ accessToken, id, refreshToken }).
• refreshTokenRoute: cookie mode sets refreshed cookies and returns 204 with an empty body; bearer mode is unchanged (200 { accessToken, refreshToken }).
• setResponseCookie derives access-token and refresh-token cookie options independently from accessTokenSignOptions.expiresIn / refreshTokenSignOptions.expiresIn, instead of sharing a single set of options.

🐞 Fixed

Authentication

• logoutRoute: clears accessToken and refreshToken cookies unconditionally, instead of only when a refreshToken cookie was present on the request; resolves the caller's identity via context.authenticate (cookie- or bearer-aware); treats an already-revoked refresh token as success instead of error; returns success when no refresh token can be resolved instead of error.
• deactivateRoute: reads the access token from the accessToken cookie in cookie mode instead of always requiring an Authorization header.

Organization

• createChangeRequestRoute: reads the access token from the accessToken cookie in cookie mode instead of always requiring an Authorization header.

🔒 Security

• Removed an undocumented bypass in getCookieTokenInfo that accepted an app-type Authorization: Bearer token to skip cookie/session validation entirely.
• getCookieTokenInfo no longer hard-codes checkIp: false; cookie-authenticated user tokens are IP-checked by default like bearer tokens.

📦 Migration

• Cookie auth hosts: Setting authMode: 'cookie' on authentication alone is not enough. Pass authMode: 'cookie' on every mounted protected service that must accept cookie sessions, and register cookie-parser middleware.
• Cookie-mode clients: Read access/refresh tokens from Set-Cookie response headers on POST /auth/login and POST /auth/token/refresh; they are no longer present in the response body.
• Manual loginWithCredentialsFeature compositions: Add logoutFeature explicitly to keep POST /auth/logout (the authService factory already does this automatically).
• Access token lifetime: If you relied on the default 2h access token lifetime, set accessTokenSignOptions: { expiresIn: '2h' } explicitly — the default is now 15m.
• Cookie auth IP checks: If your deployment's client IP can legitimately change between requests (e.g. some proxies or mobile networks), set checkIp: false explicitly in AuthenticationServiceConfiguration.
• Removed validators: Replace any direct imports of validateResourceAccess, validateOrganizationAccess, validateOrderAccess, validateMessageAccess, validateChannelAccess, verifyAuthentication, requireParam, isUUID, or isNumber with their current equivalents (isAuthenticated, hasOrgRole, ownsResource, ownsOrder, ownsMessage, ownsChannel, etc.).

⚠️ Breaking Changes

• Authentication: AuthenticationServiceConfiguration.cookieOpts.maxAge has been removed. Cookie lifetime follows the matching token's expiresIn. Remove any cookieOpts.maxAge configuration.
• Authentication: Default accessTokenSignOptions.expiresIn changed from 2h to 15m.
• Authentication: loginWithCredentialsFeature no longer composes logoutRoute. Custom compositions built directly on loginWithCredentialsFeature (outside authService) must add logoutFeature separately.
• Authentication: Cookie-mode login and refresh no longer return tokens in the response body.
• Authentication: getCookieTokenInfo no longer accepts Authorization: Bearer as a bypass path for cookie auth.
• Validators: Removed unused legacy validator exports from Common validators: validateResourceAccess, validateOrganizationAccess, validateOrderAccess, validateMessageAccess, validateChannelAccess, verifyAuthentication, requireParam, isUUID, and isNumber.

---

SDK 0.12.0 (2026-07-07)

🐞 Fixed

Authentication

• completePasswordResetRoute: revokes all active refresh tokens when a user resets their password to invalidate existing sessions across all devices.
• changePasswordRoute: revokes all active refresh tokens when a user changes their password.
• Fingerprint security check: tokenPassesSecurityCheck treats undefined and '' as equivalent; token generation normalizes fingerprint to '' at generation time.
• logoutRoute: clears auth token cookies only when refresh token revocation succeeds.

🔄 Changed

Authentication

• softDeleteRefreshTokens sets deletedAt instead of delFlg to align with refresh token revocation checks.
• refreshTokenRoute: rotates refresh tokens on each use (new jti + DB row); returns 401 on reuse of a revoked refresh token without revoking other device sessions; uses resolveRefreshTokenFromRequest for cookie/body resolution.
• logoutRoute: revokes the presented refresh token (cookie or body) after verifying it belongs to the authenticated identity.
• Cookie-based refresh reads fingerprint from the x-nb-fingerprint header (same as body path) and runs IP/UA checks. See cookie utility.

⚠️ Breaking Changes

• Cookie-based refresh (refreshTokenRoute) and cookie-based logout (logoutRoute) require the x-nb-fingerprint header. request.body.fingerprint is no longer read on the cookie path.

---

SDK 0.11.0 (2026-05-26)

✨ Added

Combinators

• mapMatchingErrorToFalse: maps only a specific matched error class to ok(false), replacing the previous mapErrorToFalse which converted all errors.

🔄 Changed

Profile (formerly User)

• Renamed user handlers, blocks, routes, schemas, features, and service to profile. See Profile service and Profile blocks.
• Updated users collection references to profiles in organization and product routes and services.
• Removed deprecated validateUserProfileAccess validator.
• Updated return type for getProfileById.

🔒 Security

Change Email

• changeEmailRoute: returns 204 instead of an error when the requested email address is already in use, preventing email enumeration.
• Uses mapMatchingErrorToFalse to convert only conflict errors to ok(false).

⚠️ Breaking Changes

• Profile rename: user service, routes, blocks, schemas, and features are renamed to profile. Update all imports from user* to profile*.
• Validators: validateUserProfileAccess has been removed. Use the updated Profile validators instead.
• Combinators: mapErrorToFalse is renamed to mapMatchingErrorToFalse and requires an error class as the first argument.

---

SDK 0.10.0 (2026-03-17)

✨ Added

Notification Management

• New service: Notification service.
• New endpoints:
  • GET /notifications/identities/:identityId — find notifications with pagination. See Notification routes.
  • POST /notifications/:notificationId/read — mark a single notification as read.
  • POST /notifications/identities/:identityId/read — batch mark as read up to an anchor notification.
• Notification blocks for create, bulk create, find, get, single update, and batch update operations.

Address Lookup

• New service: Address service with Japan Post driver.
• New endpoint: GET /addresses — find a Japanese address by postal code. See Address routes.
• Reusable in-memory LRU cache utility for address lookup results.

Organization Member Protection

• Validators to prevent removing the last owner from an organization.
• Role-assignment validation so members cannot assign roles above their own rank.
• Same-or-above role validation before deleting organization members. See Organization validators.

🐞 Fixed

Identity

• getIdentityRoute: prevents matching token records stored in the identities collection by excluding documents with jti.

Address Lookup

• Japan Post postal code handling requires a full 7-digit code at lookup time.
• Returns null for ambiguous town names instead of guessing when multiple towns share the same postal code.

🔄 Changed

Authentication Configuration

• Replace string-based expiration settings with accessTokenSignOptions, refreshTokenSignOptions, and onetimeTokenSignOptions. See Authentication service and auth utility.
• Apply shared one-time token signing options across password reset, email change, MFA, and OAuth flows.

Authorization Rules

• Strengthen organization member upsert and delete routes with additional role hierarchy checks.

---

SDK 0.9.1 (2026-01-22)

✨ Added

Authentication

• Password validation to check new password is not the same as the current password.
• Separate bcrypt compare and matches logic into two blocks; new assertDoesNotMatch block for password-must-not-match flows.

Schema Validation

• Handle type-less schemas with object-related keywords in applySchemaDefaults.
• Support for union types including object in schema validation.

🔄 Changed

• Enhanced OpenAPI schema generation with improved tag propagation and nullable schema support.

🔒 Security

• MongoDB query filter validation for NoSQL injection protection. See schema utilities and Schema component (queryFilter hardening).

---

SDK 0.9.0 (2025-11-04)

✨ Added

Location Management

• New service: Location service.
• New endpoints: POST /locations, GET /locations/:locationId, PATCH /locations/:locationId, DELETE /locations/:locationId, GET /locations. See Location routes.
• Parent-child relationship handling with automatic ancestors calculation.

Profile Follow System

• New endpoints:
  • PUT /profiles/:profileId/profile-follows/:followProfileId — create profile follow. See Profile routes.
  • DELETE /profiles/:profileId/profile-follows/:followProfileId — delete profile follow.
  • GET /profiles/:profileId/followers — get profile followers with pagination.

Organization Follow System

• New endpoints:
  • PUT /profiles/:profileId/organization-follows/:followOrganizationId — create organization follow.
  • DELETE /profiles/:profileId/organization-follows/:followOrganizationId — delete organization follow.
  • GET /organizations/:organizationId/followers — get organization followers. See Organization routes.

Product Like System

• New endpoints:
  • PUT /profiles/:profileId/product-likes/:likeProductId — create product like.
  • DELETE /profiles/:profileId/product-likes/:likeProductId — delete product like.
  • GET /products/:productId/likers — get product likers. See Product routes.

Chat Message Template Management

• New endpoints:
  • GET /message-templates — findChatMessageTemplatesRoute.
  • GET /organizations/:organizationId/message-templates — findChatMessageTemplatesForOrganizationRoute.
  • PATCH /message-templates/:messageTemplateId — updateChatMessageTemplateRoute.
  • DELETE /message-templates/:messageTemplateId — deleteChatMessageTemplateRoute.

Product Variant Bulk Operations

• New endpoints:
  • POST /products/:productId/variants/bulk, PATCH /products/:productId/variants/bulk, DELETE /products/:productId/variants/bulk, GET /products/:productId/variants. See Product routes.

Find Endpoints

• GET /profiles/identities/:identityId — find profiles by identity ID.
• GET /organizations/:organizationId/orders — find orders by organization ID.
• GET /organizations/:organizationId/products — find products by organization ID.

Identity Lock/Unlock

• New endpoints:
  • POST /identities/:identityId/lock — lockIdentityRoute.
  • POST /identities/:identityId/unlock — unlockIdentityRoute.

Chat Channel Icon Management

• New endpoint: GET /channels/:channelId/icon-upload-url — getChatChannelIconUploadUrlRoute.

Soft Delete

• withSoftDelete combinator for MongoDB collections with automatic filtering and audit trail.

🐞 Fixed

• Add missing updatedAt/createdAt timestamps to all create and update operations.
• Cast IDs to strings in all database queries for security.

🔄 Changed

• Chat message updates restricted to message owners only (admin override removed). See updateChatMessageRoute.
• Entity creation simplified: messages and products created without attachments/images; attachments managed via dedicated endpoints.

---

SDK 0.8.0 (2025-09-24)

✨ Added

Product Variant Management

• New endpoints:
  • POST /products/:productId/variants — create product variant.
  • GET /products/:productId/variants/:productVariantId — get product variant by ID.
  • PATCH /products/:productId/variants/:productVariantId — update product variant.
  • DELETE /products/:productId/variants/:productVariantId — delete product variant.
• See Product features and Product routes.

Organization Change Request System

• New endpoints:
  • createChangeRequestRoute: POST /organizations/:organizationId/change-requests.
  • findChangeRequestsForOrganizationRoute: GET /organizations/:organizationId/change-requests.

Organization Management

• updateOrganizationAsAdminRoute: PATCH /admin/organizations/:organizationId/.
• Certificate image URL added to normalized organization responses.

Multi-Factor Authentication (MFA)

• New endpoints:
  • resendMfaCodeRoute: POST /auth/mfa/resend.
  • verifyMfaCodeRoute: POST /auth/mfa/verify.
• MFA enabled via isMfaEnabled: true in service configuration. See Authentication features.

One-Time Token (OTT) Authentication

• loginWithOnetimeTokenRoute: POST /auth/ott/login.
• OAuth callback flow returns one-time tokens; frontend exchanges via OTT login endpoint.

Pagination System

• Restructured PaginationResult<T> to separate data and metadata.
• List endpoints return { data, metadata: { pagination } } instead of legacy { count, total, value }.
• paginationQueryParametersSchema and paginationSchema for standard query parameters and metadata.
• findOrganizationMembersRoute: embedded pagination via withPaginatedProperty.

🐞 Fixed

• WebSocket IP address availability in WebSocket requests.
• Pagination metadata return issues.

---

SDK 0.7.0 (2025-09-12)

✨ Added

Chat Message Attachments

• New endpoints:
  • createChatMessageAttachmentRoute: POST /messages/:messageId/attachments.
  • deleteChatMessageAttachmentRoute: DELETE /messages/:messageId/attachments/:attachmentId.
  • getChatMessageAttachmentUploadUrlRoute: GET /messages/:messageId/attachment-upload-url.

Chat Channel Messages

• getChannelMessagesRoute: GET /channels/:channelId/messages.

Chat Read Receipts

• upsertChatChannelReadStateRoute: PUT /channels/:channelId/read-state.

Chat WebSocket Subscription

• streamChatMessagesRoute: WebSocket /messages/listen for real-time message streaming.

LINE OAuth Authentication

• New endpoints:
  • lineOAuthRoute: GET /auth/oauth/line.
  • lineOAuthCallbackRoute: GET /auth/oauth/line/callback.

Product Image Management

• New endpoints:
  • POST /products/:productId/images — create product images.
  • DELETE /products/:productId/images/:imageId — delete product image.
• See Product routes.

Blocks

• Chat read-state blocks: createChatChannelReadState, updateChatChannelReadState, findChatChannelReadStates, and query/payload builders.
• Chat message blocks: createChatMessage, getChatMessageById, attachment CRUD, and normalization helpers.
• Product blocks: getProductById, findProducts, image normalization helpers.
• OAuth blocks: requestLineOAuth, authenticateLineOAuth, verifyLineOAuth.
• normalizeFile: centralized file normalization utility.

🔄 Changed

• Chat and product normalization refactored to use centralized normalizeFile utility.
• Entity creation simplified: core messages and products created without attachments/images; attachments managed via dedicated endpoints.

🐞 Fixed

• Chat attachment normalization in update responses; security ID casting; admin access restrictions for attachment operations.
• OAuth: Google and Twitter flows fixed to use provider/providerId instead of email workarounds.

---

SDK 0.6.0 (2025-08-28)

🎥 Demo Video

📹 NodeBlocks Backend SDK v0.6.0 Demo — Complete walkthrough of all new features and functionality.

---

✨ Added

Chat Message Template System

• New endpoints:
  • createChatMessageTemplateRoute: POST /message-templates.
  • getChatMessageTemplateRoute: GET /message-templates/:messageTemplateId.
• Blocks: createChatMessageTemplate, getChatMessageTemplateById.
• Features: createChatMessageTemplateFeature, getChatMessageTemplateFeature.
• Schemas: createChatMessageTemplateSchema.
• Validators: hasOrganizationAccessToMessageTemplate.

Twitter OAuth Authentication

• New endpoints:
  • twitterOAuthRoute: GET /auth/oauth/twitter.
  • twitterOAuthCallbackRoute: GET /auth/oauth/twitter/callback.
• Drivers: createTwitterOAuthDriver, verifyTwitterCallback.

Refresh Token System

• New endpoints:
  • refreshTokenRoute: POST /auth/token/refresh.
  • deleteRefreshTokensRoute: DELETE /auth/:identityId/refresh-tokens.

WebSocket Support with RxJS

• Enhanced defService to support WebSocket server integration.
• WebSocket route handling with RxJS bridging; protocol: 'ws' routes alongside HTTP routes.
• notFromEmitter and markAsFromEmitter for emitter-based message filtering.

🔄 Changed

Services

• Authentication service: added Twitter OAuth support and refresh token functionality; updated datastore to include chatMessageTemplates collection.

🐞 Fixed

• Organization blocks export issue.
• refreshTokenRoute: removed isAuthenticated validator from refresh flow.
• Configuration property names corrected (user.typeIds → identity.typeIds; user?: string → regular?: string).

---

Migration guide (upgrading from 0.6.x docs)

1. Install @nodeblocks/backend-sdk@^0.13.0 and follow the Quickstart.
2. Replace userService, /users, and users collection examples with profileService, /profiles, and profiles.
3. Replace flat token expiry keys with accessTokenSignOptions, refreshTokenSignOptions, and onetimeTokenSignOptions. Set accessTokenSignOptions: { expiresIn: '2h' } explicitly if you still need a 2h access token.
4. For cookie sessions, set authMode: 'cookie' on Authentication and every protected service you mount, register cookie-parser before those routers, and read tokens from Set-Cookie on login/refresh—not from JSON bodies.
5. Replace removed validator imports (validateResourceAccess, verifyAuthentication, requireParam, and similar) with current exports documented under Common validators and domain validator pages.
6. Use the block catalogue and domain Reference map tables to find the current route, schema, and validator contracts for each endpoint.
7. Send the x-nb-fingerprint header on cookie-mode refresh and logout requests (SDK 0.12.0).
8. Add logoutFeature to custom compositions built on loginWithCredentialsFeature outside authService (SDK 0.13.0).
9. Remove cookieOpts.maxAge; cookie lifetime follows the matching token expiresIn (SDK 0.13.0).
10. Replace mapErrorToFalse with mapMatchingErrorToFalse(errorClass, [...]) (SDK 0.11.0); see composition utilities.

---

Breaking documentation changes

• Versioned snapshots under backend_versioned_docs/version-0.6.0 and version-0.7.0 remain historical references. New integrations should use canary v2 docs at /v2/backend/next.
• Examples no longer show flat SDK imports, user* service names, or legacy pagination envelopes.
• Cookie-mode login and refresh examples no longer return access or refresh tokens in response bodies; clients must use session cookies instead.

---

Security documentation updates

• Cookie auth no longer documents an undocumented Bearer bypass on cookie-protected routes; IP checking defaults to enabled via checkIp unless explicitly disabled. See Authentication service.
• Change-email responses document 204 instead of conflict errors to reduce email enumeration; see Authentication routes.
• Organization member protection, notification ownership, and address lookup validation are documented with current access rules on their respective validators and routes pages.