@dismissible/nestjs-dismissible 0.0.2-canary.c91edbc.0 → 0.0.2-canary.d2f56d7.0

package/README.md

@@ -7,10 +7,12 @@ A powerful NestJS library for managing dismissible state in your applications. P
 ## Features
 
 - 🚀 **Simple API** - Easy-to-use service methods for get-or-create, dismiss, and restore operations
+- ⚡ **High Performance** - Built on Fastify for maximum throughput
 - 💾 **Flexible Storage** - Default in-memory storage with support for custom storage adapters (PostgreSQL, Redis, etc.)
 - 🔌 **Lifecycle Hooks** - Intercept and customize operations with pre/post hooks
+- 🔐 **JWT Authentication** - Optional JWT auth hook for securing endpoints with OIDC providers
 - 📡 **Event-Driven** - Built-in event emission for all operations
-- 🎯 **Type-Safe** - Full TypeScript support with generic metadata types
+- 🎯 **Type-Safe** - Full TypeScript support
 - 🛡️ **Validation** - Automatic validation of dismissible items
 - 📝 **Swagger Integration** - Auto-generated API documentation
 - ⚛️ **React Client** - Works out of the box with [@dismissible/react-client](https://www.npmjs.com/package/@dismissible/react-client)
@@ -41,21 +43,21 @@ export class AppModule {}
 
 The module automatically registers REST endpoints for all operations:
 
-- `GET /v1/user/:userId/dismissible-item/:itemId` - Get or create an item
-- `DELETE /v1/user/:userId/dismissible-item/:itemId` - Dismiss an item
-- `POST /v1/user/:userId/dismissible-item/:itemId` - Restore a dismissed item
+- `GET /v1/users/:userId/items/:itemId` - Get or create an item
+- `DELETE /v1/users/:userId/items/:itemId` - Dismiss an item
+- `POST /v1/users/:userId/items/:itemId` - Restore a dismissed item
 
 Example request:
 
 ```bash
 # Get or create an item
-curl http://localhost:3000/v1/user/user-123/dismissible-item/welcome-banner?metadata=version:2&metadata=category:onboarding
+curl http://localhost:3000/v1/users/user-123/items/welcome-banner
 
 # Dismiss an item
-curl -X DELETE http://localhost:3000/v1/user/user-123/dismissible-item/welcome-banner
+curl -X DELETE http://localhost:3000/v1/users/user-123/items/welcome-banner
 
 # Restore a dismissed item
-curl -X POST http://localhost:3000/v1/user/user-123/dismissible-item/welcome-banner
+curl -X POST http://localhost:3000/v1/users/user-123/items/welcome-banner
 ```
 
 ### React Client Integration
@@ -156,9 +158,6 @@ export class FeaturesController {
     const result = await this.dismissibleService.getOrCreate(
       itemId,
       userId,
-      {
-        metadata: { version: '1.0', category: 'onboarding' },
-      },
       undefined, // optional request context
     );
 
@@ -182,6 +181,33 @@ export class FeaturesController {
 }
 ```
 
+### JWT Authentication
+
+Secure your API endpoints using the JWT Auth Hook with any OIDC-compliant identity provider:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+import { JwtAuthHookModule, JwtAuthHook } from '@dismissible/nestjs-jwt-auth-hook';
+
+@Module({
+  imports: [
+    JwtAuthHookModule.forRoot({
+      enabled: true,
+      wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      issuer: 'https://auth.example.com',
+      audience: 'my-api',
+    }),
+    DismissibleModule.forRoot({
+      hooks: [JwtAuthHook],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+See the [@dismissible/nestjs-jwt-auth-hook](https://www.npmjs.com/package/@dismissible/nestjs-jwt-auth-hook) package for detailed configuration options.
+
 ### Custom Lifecycle Hooks
 
 Lifecycle hooks allow you to intercept operations and add custom logic, validation, or mutations:
@@ -189,10 +215,8 @@ Lifecycle hooks allow you to intercept operations and add custom logic, validati
 ```typescript
 import { Injectable } from '@nestjs/common';
 import { IDismissibleLifecycleHook, IHookResult } from '@dismissible/nestjs-dismissible';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
-
 @Injectable()
-export class AuditHook implements IDismissibleLifecycleHook<BaseMetadata> {
+export class AuditHook implements IDismissibleLifecycleHook {
   // Lower priority runs first (default is 0)
   readonly priority = 10;
 
@@ -215,7 +239,7 @@ export class AuditHook implements IDismissibleLifecycleHook<BaseMetadata> {
 
   async onAfterCreate(
     itemId: string,
-    item: DismissibleItemDto<BaseMetadata>,
+    item: DismissibleItemDto,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
@@ -293,42 +317,6 @@ export class AnalyticsService {
 }
 ```
 
-### Custom Metadata Types
-
-Define custom metadata types for type-safe item properties:
-
-```typescript
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
-
-interface OnboardingMetadata extends BaseMetadata {
-  step: number;
-  completedAt?: string;
-  skipped: boolean;
-}
-
-// Use in your service
-@Injectable()
-export class OnboardingService {
-  constructor(private readonly dismissibleService: DismissibleService<OnboardingMetadata>) {}
-
-  async trackStep(userId: string, step: number) {
-    const result = await this.dismissibleService.getOrCreate(
-      `onboarding-step-${step}`,
-      userId,
-      {
-        metadata: {
-          step,
-          skipped: false,
-        },
-      },
-      undefined,
-    );
-
-    return result.item;
-  }
-}
-```
-
 ### Custom Logger
 
 Provide a custom logger implementation:
@@ -376,17 +364,15 @@ The main service for interacting with dismissible items.
 
 #### Methods
 
-**`getOrCreate(itemId, userId, options?, context?)`**
+**`getOrCreate(itemId, userId, context?)`**
 
 Retrieves an existing item or creates a new one if it doesn't exist.
 
 - `itemId: string` - Unique identifier for the item
 - `userId: string` - User identifier (required)
-- `options?: ICreateItemOptions<TMetadata>` - Optional creation options
-  - `metadata?: TMetadata` - Custom metadata to attach to the item
 - `context?: IRequestContext` - Optional request context for tracing
 
-Returns: `Promise<IGetOrCreateServiceResponse<TMetadata>>`
+Returns: `Promise<IGetOrCreateServiceResponse>`
 
 **`dismiss(itemId, userId, context?)`**
 
@@ -396,7 +382,7 @@ Marks an item as dismissed.
 - `userId: string` - User identifier
 - `context?: IRequestContext` - Optional request context
 
-Returns: `Promise<IDismissServiceResponse<TMetadata>>`
+Returns: `Promise<IDismissServiceResponse>`
 
 **`restore(itemId, userId, context?)`**
 
@@ -406,12 +392,12 @@ Restores a previously dismissed item.
 - `userId: string` - User identifier
 - `context?: IRequestContext` - Optional request context
 
-Returns: `Promise<IRestoreServiceResponse<TMetadata>>`
+Returns: `Promise<IRestoreServiceResponse>`
 
 ### Module Configuration
 
 ```typescript
-interface IDismissibleModuleOptions<TMetadata extends BaseMetadata> {
+interface IDismissibleModuleOptions {
   // Custom storage module (defaults to in-memory storage)
   storage?: DynamicModule | Type<any>;
 
@@ -419,7 +405,7 @@ interface IDismissibleModuleOptions<TMetadata extends BaseMetadata> {
   logger?: Type<IDismissibleLogger>;
 
   // Lifecycle hooks to register
-  hooks?: Type<IDismissibleLifecycleHook<TMetadata>>[];
+  hooks?: Type<IDismissibleLifecycleHook>[];
 }
 ```
 
@@ -435,13 +421,13 @@ The library emits the following events:
 All events include:
 
 - `id: string` - The item identifier
-- `item: DismissibleItemDto<TMetadata>` - The current item state
+- `item: DismissibleItemDto` - The current item state
 - `userId: string` - The user identifier
 - `context?: IRequestContext` - Optional request context
 
 Dismiss and restore events also include:
 
-- `previousItem: DismissibleItemDto<TMetadata>` - The item state before the operation
+- `previousItem: DismissibleItemDto` - The item state before the operation
 
 ## Lifecycle Hooks
 
@@ -481,21 +467,19 @@ Implement the `IDismissibleStorage` interface to create a custom storage adapter
 ```typescript
 import { Injectable } from '@nestjs/common';
 import { IDismissibleStorage } from '@dismissible/nestjs-storage';
-import { DismissibleItemDto, BaseMetadata } from '@dismissible/nestjs-dismissible-item';
+import { DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
 
 @Injectable()
-export class RedisStorageAdapter<
-  TMetadata extends BaseMetadata,
-> implements IDismissibleStorage<TMetadata> {
-  async get(userId: string, itemId: string): Promise<DismissibleItemDto<TMetadata> | null> {
+export class RedisStorageAdapter implements IDismissibleStorage {
+  async get(userId: string, itemId: string): Promise<DismissibleItemDto | null> {
     // Your implementation
   }
 
-  async create(userId: string, item: DismissibleItemDto<TMetadata>): Promise<void> {
+  async create(userId: string, item: DismissibleItemDto): Promise<void> {
     // Your implementation
   }
 
-  async update(userId: string, item: DismissibleItemDto<TMetadata>): Promise<void> {
+  async update(userId: string, item: DismissibleItemDto): Promise<void> {
     // Your implementation
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dismissible/nestjs-dismissible",
-  "version": "0.0.2-canary.c91edbc.0",
+  "version": "0.0.2-canary.d2f56d7.0",
   "description": "Dismissible state management library for NestJS applications",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -19,8 +19,8 @@
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/swagger": "^11.0.0",
-    "@dismissible/nestjs-dismissible-item": "^0.0.2-canary.c91edbc.0",
-    "@dismissible/nestjs-storage": "^0.0.2-canary.c91edbc.0",
+    "@dismissible/nestjs-dismissible-item": "^0.0.2-canary.d2f56d7.0",
+    "@dismissible/nestjs-storage": "^0.0.2-canary.d2f56d7.0",
     "class-validator": "^0.14.0",
     "class-transformer": "^0.5.0"
   },

package/src/api/dismissible-item-response.dto.ts

@@ -27,12 +27,4 @@ export class DismissibleItemResponseDto {
     example: '2024-01-15T12:00:00.000Z',
   })
   dismissedAt?: string;
-
-  @ApiPropertyOptional({
-    description: 'Optional metadata associated with the item',
-    example: { version: 2, category: 'promotional' },
-    type: 'object',
-    additionalProperties: true,
-  })
-  metadata?: Record<string, unknown>;
 }

package/src/api/dismissible-item.mapper.spec.ts

@@ -22,7 +22,6 @@ describe('DismissibleItemMapper', () => {
       expect(dto.userId).toBe('test-user-id');
       expect(dto.createdAt).toBe('2024-01-15T10:00:00.000Z');
       expect(dto.dismissedAt).toBeUndefined();
-      expect(dto.metadata).toBeUndefined();
     });
 
     it('should convert dates to ISO strings', () => {
@@ -48,16 +47,5 @@ describe('DismissibleItemMapper', () => {
 
       expect(dto.userId).toBe('user-123');
     });
-
-    it('should include metadata when present', () => {
-      const item = createTestItem({
-        id: 'test-item',
-        metadata: { version: 2, category: 'test' },
-      });
-
-      const dto = mapper.toResponseDto(item);
-
-      expect(dto.metadata).toEqual({ version: 2, category: 'test' });
-    });
   });
 });

package/src/api/dismissible-item.mapper.ts

@@ -1,5 +1,5 @@
 import { Injectable } from '@nestjs/common';
-import { BaseMetadata, DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
 import { DismissibleItemResponseDto } from './dismissible-item-response.dto';
 
 /**
@@ -11,9 +11,7 @@ export class DismissibleItemMapper {
    * Convert a dismissible item to a response DTO.
    * Converts Date objects to ISO 8601 strings.
    */
-  toResponseDto<TMetadata extends BaseMetadata>(
-    item: DismissibleItemDto<TMetadata>,
-  ): DismissibleItemResponseDto {
+  toResponseDto(item: DismissibleItemDto): DismissibleItemResponseDto {
     const dto = new DismissibleItemResponseDto();
 
     dto.itemId = item.id;
@@ -24,10 +22,6 @@ export class DismissibleItemMapper {
       dto.dismissedAt = item.dismissedAt.toISOString();
     }
 
-    if (item.metadata) {
-      dto.metadata = item.metadata as Record<string, unknown>;
-    }
-
     return dto;
   }
 }

package/src/api/index.ts

@@ -1,6 +1,9 @@
 // Use cases
 export * from './use-cases';
 
+// Validation
+export * from './validation';
+
 // Cross-cutting
 export * from '../request/request-context.decorator';
 export * from './dismissible-item.mapper';

package/src/api/use-cases/dismiss/dismiss.controller.spec.ts

@@ -2,13 +2,12 @@ import { mock } from 'ts-jest-mocker';
 import { DismissController } from './dismiss.controller';
 import { DismissibleService } from '../../../core/dismissible.service';
 import { DismissibleItemMapper } from '../../dismissible-item.mapper';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
 import { createTestItem, createTestContext } from '../../../testing/factories';
 import { ResponseService } from '../../../response';
 
 describe('DismissController', () => {
   let controller: DismissController;
-  let mockService: jest.Mocked<DismissibleService<BaseMetadata>>;
+  let mockService: jest.Mocked<DismissibleService>;
   let mockResponseService: jest.Mocked<ResponseService>;
   let mapper: DismissibleItemMapper;
 

package/src/api/use-cases/dismiss/dismiss.controller.ts

@@ -1,23 +1,23 @@
-import { Controller, Delete, Param, UseFilters } from '@nestjs/common';
+import { Controller, Delete, UseFilters } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
 import { DismissibleService } from '../../../core/dismissible.service';
 import { DismissibleItemMapper } from '../../dismissible-item.mapper';
 import { RequestContext } from '../../../request/request-context.decorator';
 import { IRequestContext } from '../../../request/request-context.interface';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
 import { DismissResponseDto } from './dismiss.response.dto';
 import { ResponseService } from '../../../response/response.service';
 import { HttpExceptionFilter } from '../../../response/http-exception-filter';
 import { API_TAG_DISMISSIBLE } from '../api-tags.constants';
+import { UserId, ItemId } from '../../validation';
 
 /**
  * Controller for dismiss dismissible item operations.
  */
 @ApiTags(API_TAG_DISMISSIBLE)
-@Controller('v1/user/:userId/dismissible-item')
+@Controller('v1/users/:userId/items')
 export class DismissController {
   constructor(
-    private readonly dismissibleService: DismissibleService<BaseMetadata>,
+    private readonly dismissibleService: DismissibleService,
     private readonly mapper: DismissibleItemMapper,
     private readonly responseService: ResponseService,
   ) {}
@@ -29,12 +29,12 @@ export class DismissController {
   })
   @ApiParam({
     name: 'userId',
-    description: 'User identifier',
+    description: 'User identifier (max length: 32 characters)',
     example: 'user-123',
   })
   @ApiParam({
     name: 'itemId',
-    description: 'Unique identifier for the dismissible item',
+    description: 'Unique identifier for the dismissible item (max length: 32 characters)',
     example: 'welcome-banner-v2',
   })
   @ApiResponse({
@@ -52,8 +52,8 @@ export class DismissController {
   })
   @UseFilters(HttpExceptionFilter)
   async dismiss(
-    @Param('userId') userId: string,
-    @Param('itemId') itemId: string,
+    @UserId() userId: string,
+    @ItemId() itemId: string,
     @RequestContext() context: IRequestContext,
   ): Promise<DismissResponseDto> {
     const result = await this.dismissibleService.dismiss(itemId, userId, context);

package/src/api/use-cases/get-or-create/get-or-create.controller.spec.ts

@@ -2,13 +2,12 @@ import { mock } from 'ts-jest-mocker';
 import { GetOrCreateController } from './get-or-create.controller';
 import { DismissibleService } from '../../../core/dismissible.service';
 import { DismissibleItemMapper } from '../../dismissible-item.mapper';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
 import { createTestItem, createTestContext } from '../../../testing/factories';
 import { ResponseService } from '../../../response';
 
 describe('GetOrCreateController', () => {
   let controller: GetOrCreateController;
-  let mockService: jest.Mocked<DismissibleService<BaseMetadata>>;
+  let mockService: jest.Mocked<DismissibleService>;
   let mockResponseService: jest.Mocked<ResponseService>;
   let mapper: DismissibleItemMapper;
 
@@ -28,49 +27,10 @@ describe('GetOrCreateController', () => {
 
       mockService.getOrCreate.mockResolvedValue({ item, created: true });
 
-      const result = await controller.getOrCreate('test-user-id', 'test-item', context, undefined);
+      const result = await controller.getOrCreate('test-user-id', 'test-item', context);
 
       expect(result.data.itemId).toBe('test-item');
       expect(mockResponseService.success).toHaveBeenCalled();
     });
-
-    it('should parse metadata from query params', async () => {
-      const item = createTestItem({ id: 'test-item' });
-      const context = createTestContext();
-
-      mockService.getOrCreate.mockResolvedValue({ item, created: true });
-
-      await controller.getOrCreate('test-user-id', 'test-item', context, [
-        'version:2',
-        'category:test',
-      ]);
-
-      expect(mockService.getOrCreate).toHaveBeenCalledWith(
-        'test-item',
-        'test-user-id',
-        expect.objectContaining({
-          metadata: { version: 2, category: 'test' },
-        }),
-        context,
-      );
-    });
-
-    it('should handle single metadata value', async () => {
-      const item = createTestItem({ id: 'test-item' });
-      const context = createTestContext();
-
-      mockService.getOrCreate.mockResolvedValue({ item, created: true });
-
-      await controller.getOrCreate('test-user-id', 'test-item', context, 'version:2');
-
-      expect(mockService.getOrCreate).toHaveBeenCalledWith(
-        'test-item',
-        'test-user-id',
-        expect.objectContaining({
-          metadata: { version: 2 },
-        }),
-        context,
-      );
-    });
   });
 });

package/src/api/use-cases/get-or-create/get-or-create.controller.ts

@@ -1,23 +1,23 @@
-import { Controller, Get, Param, Query, UseFilters } from '@nestjs/common';
-import { ApiTags, ApiOperation, ApiParam, ApiResponse, ApiQuery } from '@nestjs/swagger';
+import { Controller, Get, UseFilters } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
 import { DismissibleService } from '../../../core/dismissible.service';
 import { DismissibleItemMapper } from '../../dismissible-item.mapper';
 import { RequestContext } from '../../../request/request-context.decorator';
 import { IRequestContext } from '../../../request/request-context.interface';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
 import { GetOrCreateResponseDto } from './get-or-create.response.dto';
 import { ResponseService } from '../../../response/response.service';
 import { HttpExceptionFilter } from '../../../response/http-exception-filter';
 import { API_TAG_DISMISSIBLE } from '../api-tags.constants';
+import { UserId, ItemId } from '../../validation';
 
 /**
  * Controller for get-or-create dismissible item operations.
  */
 @ApiTags(API_TAG_DISMISSIBLE)
-@Controller('v1/user/:userId/dismissible-item')
+@Controller('v1/users/:userId/items')
 export class GetOrCreateController {
   constructor(
-    private readonly dismissibleService: DismissibleService<BaseMetadata>,
+    private readonly dismissibleService: DismissibleService,
     private readonly mapper: DismissibleItemMapper,
     private readonly responseService: ResponseService,
   ) {}
@@ -30,22 +30,14 @@ export class GetOrCreateController {
   })
   @ApiParam({
     name: 'userId',
-    description: 'User identifier',
+    description: 'User identifier (max length: 32 characters)',
     example: 'user-123',
   })
   @ApiParam({
     name: 'itemId',
-    description: 'Unique identifier for the dismissible item',
+    description: 'Unique identifier for the dismissible item (max length: 32 characters)',
     example: 'welcome-banner-v2',
   })
-  @ApiQuery({
-    name: 'metadata',
-    description: 'Optional metadata as key:value pairs (can be repeated)',
-    required: false,
-    isArray: true,
-    type: String,
-    example: 'version:2',
-  })
   @ApiResponse({
     status: 200,
     description: 'The dismissible item (retrieved or created)',
@@ -57,50 +49,12 @@ export class GetOrCreateController {
   })
   @UseFilters(HttpExceptionFilter)
   async getOrCreate(
-    @Param('userId') userId: string,
-    @Param('itemId') itemId: string,
+    @UserId() userId: string,
+    @ItemId() itemId: string,
     @RequestContext() context: IRequestContext,
-    @Query('metadata') metadataRaw?: string | string[],
   ): Promise<GetOrCreateResponseDto> {
-    // Parse metadata from query params
-    const metadata = this.parseMetadata(metadataRaw);
-
-    const result = await this.dismissibleService.getOrCreate(
-      itemId,
-      userId,
-      {
-        metadata: metadata as BaseMetadata,
-      },
-      context,
-    );
+    const result = await this.dismissibleService.getOrCreate(itemId, userId, context);
 
     return this.responseService.success(this.mapper.toResponseDto(result.item));
   }
-
-  /**
-   * Parse metadata from query parameter format.
-   * Supports: `?metadata=key1:value1&metadata=key2:value2`
-   */
-  private parseMetadata(raw?: string | string[]): Record<string, string | number> | undefined {
-    if (!raw) {
-      return undefined;
-    }
-
-    const items = Array.isArray(raw) ? raw : [raw];
-    const metadata: Record<string, string | number> = {};
-
-    for (const item of items) {
-      const colonIndex = item.indexOf(':');
-      if (colonIndex > 0) {
-        const key = item.substring(0, colonIndex);
-        const value = item.substring(colonIndex + 1);
-
-        // Try to parse as number if possible
-        const numValue = Number(value);
-        metadata[key] = isNaN(numValue) ? value : numValue;
-      }
-    }
-
-    return Object.keys(metadata).length > 0 ? metadata : undefined;
-  }
 }

package/src/api/use-cases/get-or-create/index.ts

@@ -1,3 +1,2 @@
-export * from './get-or-create.request.dto';
 export * from './get-or-create.response.dto';
 export * from './get-or-create.controller';

package/src/api/use-cases/restore/restore.controller.spec.ts

@@ -2,13 +2,12 @@ import { mock } from 'ts-jest-mocker';
 import { RestoreController } from './restore.controller';
 import { DismissibleService } from '../../../core/dismissible.service';
 import { DismissibleItemMapper } from '../../dismissible-item.mapper';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
 import { createTestItem, createTestContext } from '../../../testing/factories';
 import { ResponseService } from '../../../response';
 
 describe('RestoreController', () => {
   let controller: RestoreController;
-  let mockService: jest.Mocked<DismissibleService<BaseMetadata>>;
+  let mockService: jest.Mocked<DismissibleService>;
   let mockResponseService: jest.Mocked<ResponseService>;
   let mapper: DismissibleItemMapper;
 

package/src/api/use-cases/restore/restore.controller.ts

@@ -1,23 +1,23 @@
-import { Controller, Post, Param, UseFilters } from '@nestjs/common';
+import { Controller, Post, UseFilters } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
 import { DismissibleService } from '../../../core/dismissible.service';
 import { DismissibleItemMapper } from '../../dismissible-item.mapper';
 import { RequestContext } from '../../../request/request-context.decorator';
 import { IRequestContext } from '../../../request/request-context.interface';
-import { BaseMetadata } from '@dismissible/nestjs-dismissible-item';
 import { RestoreResponseDto } from './restore.response.dto';
 import { ResponseService } from '../../../response/response.service';
 import { HttpExceptionFilter } from '../../../response/http-exception-filter';
 import { API_TAG_DISMISSIBLE } from '../api-tags.constants';
+import { UserId, ItemId } from '../../validation';
 
 /**
  * Controller for restore dismissible item operations.
  */
 @ApiTags(API_TAG_DISMISSIBLE)
-@Controller('v1/user/:userId/dismissible-item')
+@Controller('v1/users/:userId/items')
 export class RestoreController {
   constructor(
-    private readonly dismissibleService: DismissibleService<BaseMetadata>,
+    private readonly dismissibleService: DismissibleService,
     private readonly mapper: DismissibleItemMapper,
     private readonly responseService: ResponseService,
   ) {}
@@ -29,12 +29,12 @@ export class RestoreController {
   })
   @ApiParam({
     name: 'userId',
-    description: 'User identifier',
+    description: 'User identifier (max length: 32 characters)',
     example: 'user-123',
   })
   @ApiParam({
     name: 'itemId',
-    description: 'Unique identifier for the dismissible item',
+    description: 'Unique identifier for the dismissible item (max length: 32 characters)',
     example: 'welcome-banner-v2',
   })
   @ApiResponse({
@@ -52,8 +52,8 @@ export class RestoreController {
   })
   @UseFilters(HttpExceptionFilter)
   async restore(
-    @Param('userId') userId: string,
-    @Param('itemId') itemId: string,
+    @UserId() userId: string,
+    @ItemId() itemId: string,
     @RequestContext() context: IRequestContext,
   ): Promise<RestoreResponseDto> {
     const result = await this.dismissibleService.restore(itemId, userId, context);

package/src/api/validation/index.ts

@@ -0,0 +1,2 @@
+export * from './param-validation.pipe';
+export * from './param.decorators';