v2.363.6 - Nudj Platform Documentation

🔴 Release v2.363.6

⭐⭐⭐ Complex • 8 commits • 155 files

This release introduces Consumable Entitlements, a breakthrough feature that lets organizations set monthly/daily usage limits on premium features like AI asset generation, chat messages, and webhook events. We’ve also expanded the Usage dashboard to provide complete visibility of all entitlement types, upgraded the entire platform to Next.js 16.2.6 for improved performance, and fixed critical bugs around session management and giveaway validation.

What’s New

Consumable Entitlements — Set monthly or daily consumption limits on premium features like AI image generation, AI chat messages, and webhook events with intelligent reservation and refund patterns
Complete Usage Dashboard — All organization and community entitlements (Boolean, Limit, and Consumable) now visible in a unified dashboard for total transparency
Next.js 16 Platform Upgrade — Full monorepo upgrade to Next.js 16.2.6 with improved performance, security, and Next.js App Router stability
Session Security Fix — Secure session logout with proper cookie clearing for Next.js 16 compatibility
Giveaway Entry Validation — API now prevents entries to closed giveaways, eliminating invalid redemptions

Apps Updated

User App

✓ Updated - 2 changes

API

✓ Updated - 5 changes

Admin

✓ Updated - 3 changes

MCP Server

✓ Updated - 1 change

Games

✓ Updated - Framework upgrade

Website

— No changes

Detailed Changes

User App

Secure logout — Session cookies now properly cleared during sign-out, fully compatible with Next.js 16
Giveaway validation — Users can no longer submit entries to giveaways that have been closed by administrators

API

Consumable entitlements — Core runtime enforcement for ai.images_per_month, ai.chat_messages_per_month, and webhooks.events_per_month with race-safe MongoDB reservation pattern
Usage tracking — API now tracks consumption state per period with automatic period reset
Giveaway validation — API rejects reward entries when giveaway is closed, with proper validation logic
Widget cache invalidation — Community mutations now properly bust user app widget cache, ensuring fresh data
AI asset consumption — AI image generation and refinement operations now consume allocations with refund support on failure

Admin

Organization usage dashboard — New visibility into all organization-level entitlements with real-time consumption tracking
Community usage dashboard — Community managers can now see which features are enabled and consumption status per community
Consumable limits UI — Display monthly/daily consumption limits for premium features with granular usage breakdowns
AI chat gating — Chat messages now subject to consumable limits with 402 Payment Required responses when limits exceeded

MCP Server

Framework upgrade — Updated to Next.js 16.2.6 with improved performance

Games

Framework upgrade — Updated to Next.js 16.2.6 with improved performance

Admin Features

Consumable Entitlements – Control monthly/daily usage limits on premium features like AI generation, chat, and webhooks per organization and plan tier
Organization Usage Dashboard – Real-time visibility of all entitlement consumption (Boolean flags, Limit counts, Consumable usage) across your organization
Community Usage Dashboard – See which features are enabled per community and current consumption status for tracked consumables
Usage Tracking by Plan Tier – Different consumption limits for Starter, Growth, and Enterprise tiers; usage resets monthly on a per-organization basis
AI Chat Limits – Control how many chat messages each organization can use per month, with automatic billing notifications when approaching limits
Webhook Event Limits – Set monthly webhook event budgets with fail-soft enforcement (events continue but are logged as warnings)

User Features

Prevent Duplicate Giveaway Entries – Users can no longer attempt to enter giveaways after they’ve been closed by administrators
Improved Session Security – Logout now fully clears session state with proper cookie handling for modern Next.js versions
Performance Improvements – Next.js 16.2.6 upgrade brings faster builds, improved hydration, and better runtime performance

Breaking Changes

No breaking changes in this release. All changes are backward-compatible with existing integrations and API clients.

Technical Notes

Consumable Entitlements Architecture

Consumables use an efficient MongoDB findOneAndUpdate with atomic $expr operators to avoid race conditions without requiring multi-document transactions. Usage is tracked in a usage subdocument on each organization’s subscription object, keyed by entitlement name (e.g., usage["ai.images_per_month"]). Three runtime patterns demonstrated:

Fail-closed with refund (AI images): Reserves quota upfront, refunds on failure
Fail-closed simple (AI chat): Rejects request with 402 if insufficient quota
Fail-soft (webhooks): Permits dispatch but warns in logs when over limit

Period resets are computed lazily on first access each period, avoiding cron jobs.

Next.js 16 Compatibility

The monorepo upgrade to Next.js 16.2.6 includes:

Request handler modernization across all API routes (50+ files updated)
Proper async/await handling in middleware and server actions
Improved server component streaming and response handling

All changes maintain full backward compatibility with existing deployments.

Cache Invalidation Strategy

The widget cache invalidation fix ensures that mutations affecting community data properly propagate to user app widget views. This applies to birthday distributions, loyalty tier assignments, referral configs, and community metadata changes.

Usage Examples

Checking Consumable Limits (Admin API)

// Get current consumption for your organization
const usage = await adminClient.entitlements.getConsumableUsage({
  organisationId: "org_123"
});

// Response shows usage like:
// {
//   "ai.images_per_month": { used: 850, granted: 1000, periodStartedAt: "2026-06-01" },
//   "ai.chat_messages_per_month": { used: 12500, granted: 20000, periodStartedAt: "2026-06-01" },
//   "webhooks.events_per_month": { used: 45000, granted: 100000, periodStartedAt: "2026-06-01" }
// }

Consuming from an Entitlement (Service-Layer)

import { ConsumableUsageService } from "@nudj-digital/services";

const service = new ConsumableUsageService(mongoClient);

// Reserve and consume (fails if over limit)
const result = await service.consume("ai.images_per_month", orgId, {
  requested: 1,
  refundableOn: ["image-generation-failed"],
});

if (result.allowed) {
  // Proceed with image generation
  const image = await generateImage();
  if (image.failed) {
    await service.refund("ai.images_per_month", orgId, 1);
  }
}

Entitlements & Plans — Overview of Boolean, Limit, and Consumable entitlement types
Usage Dashboard — Monitoring consumption across your organization
AI Features — Using AI-powered features within your allocation
Webhooks — Event delivery and quota management

Contributors

@Derek Counihan4 commits • +3,196/-2,331 lines

@jamescockayne2 commits • +11,021/-549 lines

@SaadK941 commit • +9/-1 lines

Release Stats

Metric	Value
Total Commits	8
Lines Added	+14,351
Lines Removed	-2,873
Files Changed	155
Release Size	🔴 Massive
Complexity	⭐⭐⭐ Complex

v2.363.6 deployed on June 2, 2026

Documentation Index

​🔴 Release v2.363.6

​What’s New

​Apps Updated

User App

API

Admin

MCP Server

Games

Website

​Detailed Changes

​Admin Features

​User Features

​Breaking Changes

​Technical Notes

​Consumable Entitlements Architecture

​Next.js 16 Compatibility

​Cache Invalidation Strategy

​Usage Examples

​Checking Consumable Limits (Admin API)

​Consuming from an Entitlement (Service-Layer)

​Related Features

​Contributors

​Release Stats

🔴 Release v2.363.6

What’s New

Apps Updated

Detailed Changes

Admin Features

User Features

Breaking Changes

Technical Notes

Consumable Entitlements Architecture

Next.js 16 Compatibility

Cache Invalidation Strategy

Usage Examples

Checking Consumable Limits (Admin API)

Consuming from an Entitlement (Service-Layer)

Related Features

Contributors

Release Stats